Home|Management Portal|Index
Caché High Availability Guide
Backup and Restore
« »
   
Server:docs.intersystems.com
Instance:ENS20082
User:UnknownUser
 
-
Go to:
Search:    

This chapter outlines the factors to consider when developing a solid plan for backing up your Caché system. It discusses techniques for ensuring the integrity and recoverability of your backups, as well as suggested backup methodologies. Later sections of the chapter contain details about the procedures used to perform these tasks, either through the System Management Portal or by using Caché and third-party utilities. It discusses the following topics:

Backup strategies can differ depending upon your operating system, preferred backup utilities, disk configurations, and backup devices. If you require further information to help you to develop a backup strategy tailored for your environment, or to review your current backup practices, please contact the InterSystems Worldwide Response Center (WRC).
Backup Integrity and Recoverability
Regardless of the backup methods you use, it is critical to restore backups on a regular basis as a way to ensure that your backup strategy is a workable means of disaster recovery. The best practice is to restore every backup of the production environment to an alternate server, and then check the physical structure of the restored databases. This provides the following backup validation functions:
The backup methods described in this document preserve the physical structure of the database; therefore, a clean integrity check of the restored copy implies that the integrity of the production database was sound at the time of the backup. The converse, however, is not true; an integrity error detected on the restored copy of a database does not necessarily imply that there are integrity problems on the production database. There could, for example, be errors in the backup media. If you discover an integrity error in the restored database, immediately run an integrity check on the production database to verify the integrity of the production system.
Note:
See the Check Database Integrity section of the “Managing Caché” chapter of the Caché System Administration Guide for the details of checking database integrity.
To further validate that the application is working correctly on the restored database, you can also perform application-level checks. To perform these checks, you may need to restore journal files to restore transactional integrity. See the Importance of Journals section for more information.
Once you restore the backup and establish that it is a viable source of recovery, it is best to preserve that restored copy until you establish the next good backup. Therefore, the server on which you are validating the backup should ideally have twice the storage space required by production—space to store the last-known good backup as well as the backup your are currently validating. (Depending on your needs, you may have less stringent performance requirements of the storage device used for restoring backups, allowing for a less expensive storage solution.) In this way, the last-known good backup is always available for use in a disaster even if validation of the current backup fails. To protect the enterprise from a disaster that could destroy the physical plant, regularly ship backup media to a secure off-site location.
You can run backups during transaction processing; as a result, the backup file may contain partial transactions. When restoring from a backup, you first restore the backup file, then restore from the journal files to complete the partial transactions in the backup file. Retain all journal files corresponding to the last-known backup until you identify a new backup as the last-known good backup.
Importance of Journals
The backup of a Caché database alone is not enough to provide a viable restore of production data. In the event of a disaster that requires restoring from backup, you always apply journal files to the restored copy of the database. Applying journal files restores all journaled updates from the time of the backup, up to the time of the disaster. Also, applying journals is necessary to restore the transactional integrity of your database by rolling back uncommitted transactions (the databases may have contained partial transactions at the time of the backup).
It is critical to ensure that journal files are available for restore in the event of a disaster. Take the following steps to prevent compromising the journal files when disaster recovery requires you to restore databases.
Important:
It is critical to test the entire disaster recovery procedure from start to finish periodically. This includes backup restore, journal restore, and running simulated user activity on the restored environment.
See the Journaling chapter of this guide for more information.
Backup Methods
The two main methods of backing up Caché data are the external backup and the Caché online backup. Each of these methods have variations on how to implement them; your backup strategy can contain multiple types of backups performed at different times and with different frequency. This section describes the details and variations of the two types of backups:
External Backup
Use the external backup in conjunction with technology that provides the ability to quickly create a functional “snapshot” of a logical disk volume. Such technologies exist at various levels, such as simple disk mirrors, volume shadowing at the operating system level, or more modern snapshot technologies provided at the SAN level.
This approach is especially attractive for enterprises that have a very large amount of data, where the output of a Caché online backup would be so large as to be unwieldy. The approach is to freeze writes to all database files for the duration required to create a snapshot, then create a snapshot of the disk using the technology of choice. After you create the snapshot, thaw the system to again allow writes to the database while you copy the snapshot image to the backup media.
Caché provides the Backup.General class with class methods to simplify and enhance this technique. On nonclustered instances of Caché, these class methods pause physical writes to the database during the creation of the snapshot, while allowing user processes to continue performing updates in memory. This allows for a zero-downtime external backup on nonclustered systems. Use this mechanism with a disk technology that can create the snapshot within several minutes; if you pause the Write daemon for an extended period of time, user processes could hang due to a shortage of free global buffers.
Important:
On clustered instances of Caché, this method pauses user processes for the duration of the freeze.
In addition to pausing writes, the freeze method also handles switching journal files and writing a backup marker to the journal. The class methods that perform the database freeze and thaw operations are Backup.General.ExternalFreeze() and Backup.General.ExternalThaw() respectively. On nonclustered systems if you do not journal your databases you may lose data if the system crashes while it is suspended.
There is also a Backup.General.QuiesceUpdates() class method that blocks new database update activity and waits for existing update activity to finish within a certain period of time. See the Backup.General class documentation in the Caché Class Reference for details on the use of these methods and examples.
The following sections discuss the types of external backups and the advantages and disadvantages of each:
Concurrent External Backup
A concurrent external backup, or “dirty backup,” is the most common strategy used by large-scale production facilities that have large databases, have limited time to complete a backup, and require uninterrupted processing 24 hours a day. The utility you use to perform the backup depends on your site preference and the operating system. You may choose a native operating system utility, such as the UNIX tar utility, or a third-party utility such as Veritas or ARCserve.
Procedure Outline:
Perform a concurrent external backup using the following steps as a guide:
  1. Clear the list of data blocks modified since the last backup.
  2. Copy the Cache.dat database files.
  3. Perform a Caché incremental backup, which copies any blocks that changed while the Cache.dat files were being copied; this may cause a very brief suspension of user processes in some configurations.
See the Concurrent External Backup script section for an example.
Paused External Backup
Using a paused external backup is the second most common strategy used by large-scale production facilities that have large databases and limited time to complete a backup, but can tolerate a brief suspension of writes to databases. Organizations often use this strategy in conjunction with advanced disk technologies, such as disk mirroring. The approach is to freeze the Caché Write daemon long enough to separate a mirror copy of data and then quickly resume writes to the databases. You back up the mirror and then later rejoin it to production.
Procedure Outline:
Perform a paused external backup using the following steps as a guide:
  1. Freeze writes to the database using the ExternalFreeze() method of the Backup.General class.
  2. Separate the disk mirror from production (if using advanced disk technologies), or make a copy of the Cache.dat database files.
  3. Resume Caché writes using the ExternalThaw() method of the Backup.General class.
  4. If you split a mirror from production, back up the mirror copy of the database and rejoin the mirror to production.
See the Paused External Backup script section for an example.
Cold Backup
You generally use the cold backup strategy when your operation tolerates downtime. Often, smaller installations that do not have strict 24/7 access requirements use this strategy. Sometimes this is done only when performing a complete system backup as part of a maintenance effort such as repairing faulty hardware. In this situation, stop Caché during the backup period and restart it when the backup completes.
Procedure Outline:
  1. Stop Caché using the ccontrol command or through the Caché Cube.
  2. Perform the backup.
  3. Restart Caché using the ccontrol command or through the Caché Cube.
Online Backup
Caché implements a proprietary backup mechanism designed to cause very minimal or, in most cases, no downtime to users of the production system. The online backup captures only blocks that are in use by the database. The output goes to a sequential file. The backup file is then copied to the backup media along with any other external files such as the .cpf file, the CSP files, and external files used by the application.
The Caché backup uses a multipass scan to backup database blocks. It is expected that each pass has a reduced list of modified blocks and that generally three passes are sufficient to complete a backup. During the entire final pass and for a brief moment during each prior pass, the system pauses writes to the database. If the backup list contains only new-format databases (8-KB block size), only physical writes to the database are paused while user processes are allowed to continue performing updates in memory. If the backup list contains any old-format (2-KB block size) databases, or if it is a clustered Caché environment, then all user activity is paused for these multiple brief periods.
The concurrent Caché online backup strategy is used when the backup must have the least impact on Caché processes. This is a strategy used across all sizes of production facilities.
In the case where 8-KB databases are used in a nonclustered environment, it is possible to back up the database without pausing user processes. The backup procedure incorporates multiple passes to copy the data, where each consecutive pass copies any data blocks that changed during the previous pass. During the last pass, writes to the disk are paused, while writes to the buffers are still allowed, thus users are not impacted (provided there are sufficient global buffers). In a clustered environment (or when some 2-KB databases are backed up), user processes are paused briefly during the final pass of the backup.
There are three different types of concurrent online backups: full, cumulative, and incremental, which can be combined to manage a trade-off between the size of the backup output, and the time needed to recover from the backup:
Full Backup
Writes an image of all in-use blocks to the backup media.
Cumulative Backup
Writes all blocks that have been modified since the last full backup. Must be used in conjunction with a previous full backup.
Incremental Backup
Writes all blocks that have been modified since the last backup of any type. Must be used in conjunction with a previous full backup and (optionally) subsequent cumulative or incremental backups.
Caché online backup writes all database blocks to a single file (or set of tapes) in an interleaved fashion. When an extremely large amount of data is backed up using online backup, restores can become somewhat cumbersome. This should be considered when planning your backup strategy. The restore validation process discussed above helps resolve limitations in this area by providing an online, restored copy of the databases.
When using incremental or cumulative backup, the same backup validation method explained earlier in this document should of course be used. After each incremental or cumulative backup is performed, it can be immediately restored to the alternate server. As an example, a strategy of weekly full backups and daily incremental backups can work well because each daily backup only contains blocks modified that day. Each day restore that incremental to the alternate server, and check integrity.
As discussed previously, overwriting the warm copy of the last known good backup when restoring the backup currently being validated should be avoided. The same concept applies when restoring an incremental to the existing restored database. After the backup is established as being the last known good backup and before applying the next day’s incremental or cumulative backup to it, a copy should be saved so that the last known good backup is always online and ready for use in case the subsequent incremental restore fails. If a restored backup fails an integrity check, it must be discarded and cannot be used as a target of a subsequent incremental restore.
When restoring a system from a Caché backup, first restore the most recent full backup, followed by the most recent cumulative backup, and then all incremental backups taken since the cumulative backup.
Configuring Caché Backup Settings
You can configure the Caché database backup settings from the [Home] > [Configuration] > [Database Backup Settings] and the [Home] > [Task Manager] pages of the System Management Portal.
From the System Management portal you can perform the following configuration tasks:
Define Database Backup List
Caché maintains a database list that specifies the databases to be backed up. You can display this list by opening the [Home] > [Configuration] > [Database Backup Settings] > [Backup Database List] page of the System Management Portal.
Use the arrow buttons to move the databases you do not want to back up to the Available list and the databases you do want to back up to the Selected list. Click Save.
When you add a new database to your system, Caché automatically adds it to the database list. If you do not need to include the new database in your backup plan, be sure to remove it from the Backup Database List.
This database list is ignored by the FullAllDatabases backup task, which performs a backup of all databases excluding the CACHETEMP, CACHELIB, DOCBOOK, and SAMPLES databases.
If you update the Caché-supplied CACHELIB and DOCBOOK databases, you can add them to the database list and run a FullDBList backup as a base for subsequent backup tasks.
You can also maintain the backup database list using the Backup.General.AddDatabaseToList() and Backup.General.RemoveDatabaseFromList() methods. See the Backup.General class description in the Caché Class Reference for details on using these methods.
Configure Backup Tasks
Caché provides four different types of backup tasks; each is listed as an item on the Database Backup Settings menu. The four backup tasks are:
These are predefined backup tasks that an operator can run on-demand from the [Home] > [Backup] page of the portal. You can also schedule combinations of these backup tasks using the Task Manager. See the Schedule Backup Tasks section later in this chapter for details.
The process for configuring each of these tasks is the same. The Name, Description, and Type fields are read-only and reflect the menu choice as described in the following table.
Backup Task Descriptions
Name Description Type
FullAllDatabases Full backup of all commonly updated databases, whether or not they are in the Backup Database List. Full
FullDBList Full backup of the Caché databases listed in the Backup Database List. Full
IncrementalDBList Incremental backup of changes made to the data since the last backup, whether full or cumulative. Backup is performed on the databases currently listed in the Backup Database List. Incremental
CumuIncrDBList Cumulative and Incremental backup of all changes made to the data since the last full backup. Backup is performed on the databases currently listed in the Backup Database List. Cumulative
You can send backup output to a directory on disk or to magnetic tape. Select one of the two options:
  1. To back up to a directory on disk, specify the file pathname in the Device field. Click Browse to select a directory.
  2. To back up to magnetic tape, select the Save to Tape check box, and specify a Tape Number from the list of available tape device numbers.
    See the Identifying Devices section of the Caché I/O Device Guide for detailed information regarding tape numbers.
The Define Database Backup List section describes how to maintain the Backup Database List.
Backup File Names
By default, backup files are stored in CacheSys\Mgr\Backup. The backup log files are stored in the same directory. Backup files have the suffix .cbk. Backup log files have the suffix .log.
Backup files and backup log files use the same naming conventions:
Where nnn is a sequence number incremented for that backup task on that date. Caché creates a log file for every backup attempt; successful, failed, or aborted. Caché creates a backup file only upon successful backup, but its increment number matches the corresponding log file increment number.
For example: You perform three FullDBList backup operations on June 4, 2006, the first successful, the second aborted, the third successful. This generates three .log files, numbered 001, 002, and 003, but only two .cbk files, numbered 001 and 003.
The backup files:
FullDBList_20060604_001.cbk
FullDBList_20060604_003.cbk
The matching log files:
FullDBList_20060604_001.log
FullDBList_20060604_002.log
FullDBList_20060604_003.log
Schedule Backup Tasks
You should ideally set up a schedule for running backups. Backups are best run at a time when there are the least amount of active users on the system.
In addition to the four backup tasks supplied with Caché, you can create additional definitions of these four backup tasks. For example, you could create two full backup tasks, one to save the backup to a disk file, the other to save the backup to a tape. Or, to alternate backups between two disk drives, you could create a backup task for each drive.
Use the Caché Task Manager to schedule these backup tasks:
  1. Navigate to the [Home] > [Task Manager] page of the System Management Portal.
  2. Specify the Name, Description, Backup Type, and output location.
You can delete any task you add by clicking Delete on its row on the Task Schedule page.
Managing Caché Online Backups
You can run Caché database backup tasks and view backup history from the [Home] > [Backup] page of the System Management Portal. If you schedule additional backup tasks using the Task Manager, you can manage those from the [Home] > [Task Manager] page of the System Management Portal.
From the System Management portal you can perform the following backup tasks:
When you add a new database to your system, you must perform a full backup. You cannot perform an incremental backup, or restore a database, until a full backup exists.
After installing Caché, InterSystems recommends that you perform a FullAllDatabases backup to establish a complete backup for subsequent use by the other backup tasks.
Run Backup Tasks
There are four types of backup tasks you can run from the System Management Portal, each having its own menu item:
You must have performed a full backup on a database before performing an incremental or cumulative backup on that database.
Read the Run Backup Task box to verify that the settings are correct. If the backup options are correct, click OK to start the backup.
While running a backup from the [Home] > [Backup] > [Run Backup] page, you can view the status of the running backup by clicking the text next to Backup started. See Monitor Backup Status for details.
Performing Multivolume Backups
A backup, particularly a full backup, may require multiple tape volumes, or multiple disk files. Currently, there is no way to perform a multivolume backup using the System Management Portal. If you require a multivolume backup use the ^BACKUP utility. If a disk full condition occurs, Caché prompts you for the name of another disk file on another disk.
In the event of an error during backup, you cannot restart the backup on a second or subsequent volume. You must restart the backup from the beginning.
View Backup Status
Click View on the running backup process to monitor the progress of the backup operation. The same information is recorded in the log file for that backup operation, which you can later view from the View Backup History page.
When Caché begins a backup, it updates the Time and Status columns of the listing. The Time column records the date and time that the backup was initiated, not when it completed. The Status column is updated to Running.
Upon completion of a backup, Caché again updates the Status column to indicate the final status of the backup. Completed indicates the backup successfully completed. Failed indicates the backup could not be performed or was aborted by the operator.
One cause of backup failure is trying to perform a backup on a dismounted database.
View Backup History
Every backup operation creates a separate backup log file. The logs follow the naming convention described in Backup File Names.
From the portal you can view a list of system backup logs from completed backup tasks:
  1. Navigate to the [Home] > [Backup] page of the System Management Portal.
  2. Click View Backup History in the right-hand column to display the [Home] > [Backup] > [View Backup History] page.
  3. To view the contents of a particular file, click View in the right-hand column of the appropriate row. You can view the contents of a backup log file and search for a string within that file.
Handle Backup Errors
In the event of an error during backup, the backup utility allows you to retry the device on which the error occurred. Alternatively, you can abort the backup.
On stand-alone systems (those not clustered), if you abort a backup regardless of the type, the next backup must be a full backup. This full backup on a stand-alone system does not block access to the database.
If a backup encounters any I/O errors, the backup aborts and logs a system error in the cconsole.log file, viewable by the Backup utility, the SYSLOG character-based utility, or any text file viewer. The log file allows you to quickly see where the problem occurred so that you can fix it.
Back Up Selected Globals and Routines
You may want to back up only selected globals or routines in a database. The System Management Portal offers options to perform these tasks. The following are a few cases of where these options are helpful:
You can also selectively back up and restore source code (.MAC, .INC, and .INT files), or both source and object code (.OBJ files) using the Export and ImportDir methods of the %SYSTEM.OBJ class.
Routines and globals are backed up into standard format files. These files are referred to as RSA (routine save) and GSA (global save) files.
Restoring from a Backup
If any problem arises that renders your data inaccessible or unusable, you can recreate that data by restoring the affected database(s) from backup files and applying the changes recorded in the journal files.
When you are restoring an incremental or cumulative backup, the target database must be in exactly the same state as when you restored the previous full backup. You must prevent all updates to the database that you restored from the full backup until you restore all subsequent incremental and cumulative backups.
Failing to heed this warning can result in the incremental/cumulative restore producing a degraded database.
If the previous full backup was an external backup, and the external backup is restored before Caché is started (started to apply the incremental) then there is the possibility that updates during startup could modify the restored full, thus invalidating the incremental that needs to be restored. Special care must be taken to avoid this. If the external is to be restored in place, then Caché must be started and those databases dismounted before the external backup is restored. The databases can then be mounted with switch 10 set for the purpose of restoring the incremental. Alternatively, you can restore the external to alternate directory paths, restore the subsequent incremental backups, and then move them into place.
To perform a restore, use the following strategy:
  1. Identify which Caché databases require restoration.
  2. Restore the last full backup of those Caché databases.
  3. If you have done cumulative incremental backups since the full backup, restore the last one.
  4. Restore all incremental backups done since the last full backup in the order in which the backups were performed, or restore the last cumulative incremental backup, whichever was more recent.
  5. Apply the changes in the journal file for the directories restored or selected directories and globals you specify.
  6. Perform a full backup of the restored system.
Caution:
If you backed up with a UNIX or OpenVMS backup utility, use the same utility to restore.
Using the Backup History to Recreate the Database
The Backup utility maintains a backup history. The Restore utility prompts you for the backup(s) to restore according to their order in the backup history.
Note:
On Caché platforms that support access to the same database from multiple computers, you should always back up a given directory from the same computer, so that its complete backup history is available if you need to restore the directory.
When you select one of the three restore options on the BACKUP main menu, the utility asks you to enter the name of the device holding the first backup to be restored. The default the first time you enter a restore option is the device the last full backup was sent to, if there was one.
Caché helps you restore backups in logical order. After restoring the last full backup, the utility uses the backups in the Backup History to suggest the next logical backup for you to restore. It cycles through all of the backups in this way.
Having already prompted you with the last full backup, it prompts you to restore subsequent backups in the following order:
  1. It prompts you for the most recent cumulative incremental backup after the last full backup, if one exists.
  2. After restoring the most recent cumulative incremental backup, if there was one, it prompts you to restore all incremental backups since the last cumulative incremental backup (or if none exists, since the last full backup). It does so in order from the first to the most recent.
    You can override the suggested backups in the restore process. Remember, however, that an incremental or cumulative incremental backup does not represent a complete copy of your disk. You can restore an incremental backup only after restoring a full backup.
Suspending Database Access During a Restore
In most cases, the database you are restoring is not fully independent of the other databases on the system. For this reason, it is recommended that all user activity be suspended during restore. Even if you are the only user on your system, you still want to restrict login access if any users can log in remotely to your system.
You can, however, restore a database with users active on other databases. All databases being restored are dismounted during the restore. Therefore, if you did not suspend database access, users who try to access the databases being restored receive <PROTECT> errors.
Restoring Database Properties
If the characteristics of a directory have changed by the time you do a restore, the restore utility handles these situations. It creates Caché databases as necessary and modifies their characteristics as appropriate, to return them to the state they were in at the time the backup was completed.
Error Handling for Restore
If an error occurs while you are restoring, you are given these options:
Caché Backup Utilities
Caché provides utilities to perform backup and restore tasks. The ^BACKUP routine provides menu choices to run common backup procedures, which you can also run independently and in some cases non-interactively using scripts. The utility names are case-sensitive. Run all these utilities from the %SYS namespace.
Perform Backup and Restore Tasks Using ^BACKUP
The Caché ^BACKUP utility allows you to perform Caché backup and restore tasks from a central menu as shown in the following example:
 
%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
 
Option? 
Enter the appropriate menu number option to start the corresponding routine. Press Enter without entering an option number to exit the utility.
Subsequent sections in this document describe the utilities started by choosing each option:
Maintain Database Backup List
Note:
When editing the database list use the database name, not the directory name. This is consistent with the way the backup configuration works in the System Management Portal.
The Caché ^BACKUP utility allows you to backup Caché databases or to restore an already created backup. If a list of databases has not been created then all databases will be included in the backup. If a list is created that list will apply to all aspects of the backup system including calls to LISTDIRS^DBACK and CLRINC^DBACK for scripted backups.
%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
 
Option? 4
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 3
The following 4 databases are included in backups
     CACHEAUDIT               C:\Program Files\CacheSys\Mgr\cacheaudit\
     CACHESYS                 C:\Program Files\CacheSys\Mgr\
     DOCBOOK                  C:\Program Files\CacheSys\Mgr\Docbook\
     USER                     C:\Program Files\CacheSys\Mgr\User\
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 4
The following is a list of all databases in the configuration.
Databases which are part of the backup are marked with (*)
     (*) CACHEAUDIT           c:\program files\cachesys\mgr\cacheaudit\
         CACHELIB (Read Only) c:\program files\cachesys\mgr\cachelib\
     (*) CACHESYS             c:\program files\cachesys\mgr\
     (*) DOCBOOK              c:\program files\cachesys\mgr\docbook\
         SAMPLES              c:\program files\cachesys\mgr\samples\
     (*) USER                 c:\program files\cachesys\mgr\user\
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 5
 
=====Last Full Backup Information=====
 
Date: 19 Jan 2007
Description: Full backup of all databases that are in the backup database list.
Device: c:\program files\cachesys\mgr\backup\FullDBList_20070119_001.cbk
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 1
Enter database to add?  SAMPLES
Enter database to add?
You've selected SAMPLES to be added to the backups
Are you sure you want to do this (yes/no)? y
Completed.
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 3
The following 5 databases are included in backups
     CACHEAUDIT               C:\Program Files\CacheSys\Mgr\cacheaudit\
     CACHESYS                 C:\Program Files\CacheSys\Mgr\
     DOCBOOK                  C:\Program Files\CacheSys\Mgr\Docbook\
     SAMPLES                  C:\Program Files\CacheSys\Mgr\Samples\
     USER                     C:\Program Files\CacheSys\Mgr\User\
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 2
Enter database to remove (^ when done)?  SAMPLES
Enter database to remove (^ when done)?
You've removed SAMPLES from the backups
Are you sure you want to do this? y
Completed.
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option? 3
The following 4 databases are included in backups
     CACHEAUDIT               C:\Program Files\CacheSys\Mgr\cacheaudit\
     CACHESYS                 C:\Program Files\CacheSys\Mgr\
     DOCBOOK                  C:\Program Files\CacheSys\Mgr\Docbook\
     USER                     C:\Program Files\CacheSys\Mgr\User\
 
1) Add a database to the backup
2) Remove a database from the backup
3) Show current list of databases included in backups
4) Show list of available databases
5) Display last full backup information
 
Option?
Back Up Databases Using ^DBACK
The Caché ^DBACK utility allows you to backup Caché databases. If a list of databases has not been created then all databases will be included in the backup. If a list is created that list will apply to all aspects of the backup system including calls to LISTDIRS^DBACK and CLRINC^DBACK for scripted backups.
 
%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
 
Option? 1
 
                 Cache 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
1 =>
 
External Entry Points for ^DBACK
BACKUP^DBACK
The following 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)
Starting with this version of Caché the meanings of the following arguments have changed. Because of 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.
Argument Description
argfile No longer used; always use a NULL value
type Type of backup. Values:
I — Incremental
C — Cumulative
F — Full
E — External full backup
desc Description stored in the backup label and in the history global. Free form text string that can be NULL.
The following arguments are ignored (and, therefore, not required) for backups of type E.
Argument Description
outdev Output device for the backup; can be a file name or tape device.
kiljrn
Y — switch journal file after backup
N — ignored
logfile
File name — Send a copy of all messages that would be sent to the terminal to this file.
Null value — no log file
mode
“NOISY” — Default, print all text on terminal
“QUIET” — Only display text related to abnormal conditions
“NOINPUT” — No terminal is attached to this process. No output will be sent to the terminal and if a read must be executed, the backup is aborted.
It is advisable to have a log file. NOTE: This switch only affects what is displayed at the terminal, the logfile is always “NOISY.”
clrjrn
Y — switch the journal file
N — ignored
swjrn
Y — switch the journal file after backup
N — Do not switch the journal file. This is overridden if clrjrn or kiljrn is Y
nwjrnfil Ignored
The following are two optional arguments:
Argument Description
quietimeout Number of seconds to wait for system to quiesce before aborting backup. A zero (0) or negative value indicates to wait indefinitely (default = 60).
taskname Task name passed by Backup.General.StartTask(); used internally by Caché.
Using these external entry points requires read/write access to the SYS global for all modes. A 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 history global as being the LASTFULL backup.
If SWITCH 10 or 13 is set when this routine is called they remain set throughout the backup. If switch 13 is set then it will be converted into a switch 10 since backup needs to do Sets and Kills. It will be restored upon exit.
Variables defined by this entry point are NEWed but those defined within the body of the ^DBACK procedure are not.
Return values:
LISTDIRS^DBACK
LISTDIRS^DBACK(file,mode) ; ; This procedure takes a file name and a mode.
CLRINC^DBACK
CLRINC^DBACK(mode) — clears the incremental backup bits
Restore Databases Using ^DBREST
The Caché ^DBREST database restore utility performs the following actions:
The ^DBREST menu options 1 and 2 are the equivalent of choosing options 2 and 3 from the ^BACKUP menu.
%SYS>Do ^DBREST
 
                        Cache DBREST Utility
         Restore database directories from a backup archive
 
Restore: 1. All directories
         2. Selected and/or renamed directories
         3. Exit the restore program
    1 =>
The following sections describe the process of choosing each option:
You can also perform these functions non-interactively in a script. See the External Entry Points of ^DBREST section for details.
Restore All Databases Using ^DBREST
Choosing 1 from the ^DBREST menu is equivalent to choosing 2 from the ^BACKUP menu:
%SYS>Do ^BACKUP
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
 
Option? 2
Proceed with restoring ALL directories Yes => n
 
Restore: 1. All directories
         2. Selected and/or renamed directories
         3. Exit the restore program
    1 => 3
 
 
1) Backup
2) Restore ALL
3) Restore Selected or Renamed Directories
4) Edit/Display List of Directories for Backups
 
Option?
The following procedure restores all directories:
  1. USER>DO ^%CD
     
    Namespace: %SYS
    You're in namespace %SYS
    Default directory is c:\cachesys\mgr\
    %SYS>DO ^BACKUP
  2. Select Restore ALL from the Backup utility options. This option restores all directories that are on the backup medium.
    %SYS>Do ^BACKUP
     
    1) Backup
    2) Restore ALL
    3) Restore Selected or Renamed Directories
    4) Edit/Display List of Directories for Backups
     
    Option? 
  3. Confirm that you want to restore all directories:
    Proceed with restoring ALL directories Yes=>
    Restore: 1. All directories
             2. Selected and/or renamed directories
             3. Exit the restore program
        1 =>
  4. Indicate whether you want to suspend Caché processes while restoring takes place. InterSystems recommends suspending processes.
    Do you want to set switch 10 so that other processes will be
    prevented from running during the restore? Yes =>
  5. Specify the first file from which to restore. You can press Enter to accept the default file, which is the last full backup.
    Specify input file for volume 1 of backup 1
     (Type STOP to exit)
    Device: c:\cachesys\mgr\backup\FullAllDatabases_20060323_001.cbk =>
    
  6. Check that the description of the backup is correct and verify that this is the file you want to restore.
    This backup volume was created by:
       Cache for Windows (Intel) 5.1
     
    The volume label contains:
       Volume number      1
       Volume backup      MAR 23 2006 09:52AM Full
       Previous backup    MAR 22 2006 11:00AM Incremental
       Last FULL backup   MAR 16 2006 11:00AM
       Description        Full backup of ALL databases, whether or not they are in
                          the backup database list.
       Buffer Count       0
    Is this the backup you want to start restoring? Yes =>
    
  7. The utility tells you which directories it will restore, and the restore proceeds.
    The following directories will be restored:
    c:\cachesys\mgr\
    c:\cachesys\mgr\cacheaudit\
    c:\cachesys\mgr\samples\
    c:\cachesys\mgr\test\
    c:\cachesys\mgr\user\
    
     
    ***Restoring c:\cachesys\mgr\ at 10:46:01
    146045 blocks restored in 241.3 seconds for this pass, 146045 total restored.
     
    ***Restoring c:\cachesys\mgr\cacheaudit\ at 10:50:01
    53 blocks restored in 0.0 seconds for this pass, 53 total restored.
     
    ***Restoring c:\cachesys\mgr\samples\ at 10:50:01
    914 blocks restored in 0.6 seconds for this pass, 914 total restored.
     
    ***Restoring c:\cachesys\mgr\test\ at 10:50:02
    53 blocks restored in 0.0 seconds for this pass, 53 total restored.
     
    ***Restoring c:\cachesys\mgr\user\ at 10:50:02
    124 blocks restored in 0.1 seconds for this pass, 124 total restored.
     
    ***Restoring c:\cachesys\mgr\ at 10:50:02
    5 blocks restored in 0.0 seconds for this pass, 146050 total restored.
     
    ***Restoring c:\cachesys\mgr\cacheaudit\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 54 total restored.
     
    ***Restoring c:\cachesys\mgr\samples\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 915 total restored.
     
    ***Restoring c:\cachesys\mgr\test\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 54 total restored.
     
    ***Restoring c:\cachesys\mgr\user\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 125 total restored.
     
    ***Restoring c:\cachesys\mgr\ at 10:50:02
    3 blocks restored in 0.0 seconds for this pass, 146053 total restored.
     
    ***Restoring c:\cachesys\mgr\cacheaudit\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 55 total restored.
     
    ***Restoring c:\cachesys\mgr\samples\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 916 total restored.
     
    ***Restoring c:\cachesys\mgr\test\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 55 total restored.
     
    ***Restoring c:\cachesys\mgr\user\ at 10:50:02
    1 blocks restored in 0.0 seconds for this pass, 126 total restored.
     
    
  8. Specify the input file for the next incremental backup to restore, or enter STOP if there are no more input files to restore.
    Specify input file for volume 1 of backup following MAR 23 2006  09:52AM
     (Type STOP to exit)
    Device: stop
    
  9. Indicate whether you want to restore other backups. When you answer Yes, the procedure repeats from step 3. When you respond No, Caché mounts the databases you have restored.
    Do you have any more backups to restore? Yes => No
    Mounting c:\cachesys\mgr\
        c:\cachesys\mgr\       ... (Mounted)
     
    Mounting c:\cachesys\mgr\cacheaudit\
        c:\cachesys\mgr\cacheaudit\  ... (Mounted)
     
    Mounting c:\cachesys\mgr\samples\
        c:\cachesys\mgr\samples\  ... (Mounted)
     
    Mounting c:\cachesys\mgr\test\
        c:\cachesys\mgr\test\  ... (Mounted)
     
    Mounting c:\cachesys\mgr\user\
        c:\cachesys\mgr\user\  ... (Mounted)
     
    
  10. Specify which journal entries you want to apply to the restored databases and the name of the journal file you are restoring. Normally, you select Option 1 and apply only those changes that affect the directories you have just restored.
    Restoring a directory restores the globals in it only up to the
    date of the backup.  If you have been journaling, you can apply
    journal entries to restore any changes that have been made in the
    globals since the backup was made.
     
    What journal entries do you wish to apply?
     
         1. All entries for the directories that you restored
         2. All entries for all directories
         3. Selected directories and globals
         4. No entries
     
    Apply: 1 =>
    
  11. Restore from the journal files begins.
    We know something about where journaling was at the time of the backup:
    0: offset 172940 in c:\cachesys\mgr\journal\20060323.002
     
    Use current journal filter (ZJRNFILT)? No
    Use journal marker filter (MARKER^ZJRNFILT)? No
    Updates will not be replicated
     
    The earliest journal entry since the backup was made is at
    offset 172940 in c:\cachesys\mgr\journal\20060323.002
     
    Do you want to start from that location? Yes => Yes
    Final file to process (name in YYYYMMDD.NNN format): <20060323.003> [?]
          =>
     
    Prompt for name of the next file to process? No => No
     
    Provide or confirm the following configuration settings:
     
    Journal File Prefix: =>
     
    Files to dejournal will be looked for in:
         c:\cachesys\mgr\journal\
         c:\journal\altdir\
    in addition to any directories you are going to specify below, UNLESS
    you enter a minus sign ('-' without quotes) at the prompt below,
    in which case ONLY directories given subsequently will be searched
     
    Directory to search: <return when done>
    Here is a list of directories in the order they will be searched for files:
         c:\cachesys\mgr\journal\
         c:\journal\altdir\
    The journal restore includes the current journal file.
    You cannot do that unless you stop journaling or switch
         journaling to another file.
    Do you want to switch journaling? Yes => Yes
    Journaling switched to c:\cachesys\mgr\journal\20060323.004
     
    You may disable journaling the updates for faster restore; on the other hand,
    you may not want to do so if a database to restore is being shadowed.
    Do you want to disable journaling the updates? Yes => yes
    Updates will NOT be journaled
     
     
    c:\cachesys\mgr\journal\20060323.002
      61.32%  65.03%  68.44%  72.21%  75.86%  79.26%  82.73%  86.08%  89.56%  
      92.99%  96.07%  98.87%100.00%
    ***Journal file finished at 11:03:31
     
     
    c:\cachesys\mgr\journal\20060323.003
      16.17%  17.10%  17.90%  18.90%  20.05%  21.33%  22.58%  23.81%  25.15%  
      26.32%  27.65%  28.85%  30.08%  31.37%  32.59%  33.98%  35.16%  36.25%  
      37.32%  38.41%  39.55%  40.72%  41.81%  42.83%  43.85%  44.89%  46.00%  
      47.15%  48.24%  49.28%  50.32%  51.41%  52.54%  53.71%  54.76%  55.80%  
      56.85%  57.97%  59.10%  60.16%  61.17%  62.19%  63.24%  64.32%  65.18%  
      66.02%  66.87%  67.71%  68.52%  69.34%  70.14%  70.96%  71.76%  72.60%  
      73.58%  74.51%  75.43%  76.35%  77.26%  78.17%  79.07%  79.69%  80.31%  
      80.93%  81.56%  82.20%  82.83%  83.47%  84.27%  87.00%  88.57%  91.65%  
      93.03%  96.09%  97.44%  99.04%100.00%
    ***Journal file finished at 11:03:32
     
    Journal reads completed. Applying changes to databases...
      14.29%  28.57%  42.86%  57.14%  71.43%  85.71% 100.00%
     
    [journal operation completed]
    Replication Enabled
     
     
    1) Backup
    2) Restore ALL
    3) Restore Selected or Renamed Directories
    4) Edit/Display List of Directories for Backups
     
    Option?
    
Restore Selected or Renamed Databases Using ^DBREST
The Restore Selected or Renamed Directories option lets you select which directories to restore from the backup medium. It also allows you to restore a database to a different directory name.
The following example shows how to restore selected or renamed directories.
  1. %SYS>DO ^BACKUP
  2. Select Restore Selected or Renamed Directories from the Backup Menu.
  3. Indicate whether you want to suspend Caché processes while restoring takes place. InterSystems recommends suspending processes.
    Do you want to set switch 10 so that other Cache processes
    will be prevented from running during the restore? Yes =>
  4. Specify the first file from which to restore. You can press <Enter> to accept the default file, which is the last full backup.
    Specify input file for volume 1 of backup 1
     (Type STOP to exit)
    Device: c:\cachesys\mgr\backup\IncrementalDBList_20060323_001.cbk =>
    
  5. Check that the description of the backup is correct and verify that this is the file you want to restore.
    This backup volume was created by:
       Cache for Windows (Intel) 5.1
     
    The volume label contains:
       Volume number      1
       Volume backup      MAR 23 2006 11:03AM Full
       Previous backup    MAR 23 2006 09:52AM Full
       Last FULL backup   MAR 23 2006 09:52AM
       Description        Incremental backup of all databases that are in the backup
                          database list.
       Buffer Count       0
    Is this the backup you want to start restoring? Yes =>
    
  6. As the utility prompts you with directory names, specify which databases you want to restore, and in which directories you want to restore them:
    For each database included in the backup file, you can:
     
     -- press RETURN to restore it to its original directory;
     -- type X, then press RETURN to skip it and not restore it at all.
     -- type a different directory name.  It will be restored to the directory
        you specify.  (If you specify a directory that already contains a
        database, the data it contains will be lost).
     
    c:\cachesys\mgr\ =>
    c:\cachesys\mgr\cacheaudit\ =>
    c:\cachesys\mgr\test\ =>
    c:\cachesys\mgr\user\ =>
     
    Do you want to change this list of directories? No =>
     
    
  7. After responding to each directory prompt, you see the prompt: “Do you want to change this list of directories? No=>”. Answer Yes if you want to edit your choices, or press Enter to confirm them.
  8. Continue the Restore from Step 8 in the procedure for restoring all directories, as specified earlier in this chapter.
External Entry Points of ^DBREST
The Caché restore utility, ^DBREST, provides a non-interactive execution option using external entry points. You can write a script to implement unattended restores by calling one of these two entry points. Both entry points are functions, which return the status of the call. All arguments are input only.
The following table describes the input arguments used for both functions.
Argument Description
quietmode A value indicates the operation is in quiet (non-interactive) mode; must be a non-null value for this external call, typically 1.
allowupd Indicator whether or not to allow updates during the restore process:
1 — allow updates during the restore process
0 — do not allow updates
inpdev Input device that contains the backup. If this device is a tape device, the utility prompts you to specify the device for the next volume.
dirlist File name containing a list of directories to restore. One record for each directory to be restored has to be present. Ignored for the EXTALL entry point.
jrnopt Options to restore the journal:
1 — All directories for which you just restored the backup
2 — All directories in the journal
3 — Selected directories and globals specified by the jdirglo argument
4 — No directories
jrnfile Journal file. If null, the utility uses the current file, which is stored in the ^%SYS("JOURNAL“,”CURRENT") global.
jdirglo Only used when jrnopt is 3. This is the name of the file containing selection criteria for directories and globals for the journal restore.
Requirements of the file indicated by jdirglo:
Argument Description
DirName Name of the directory that you want to restore the journal on.
RestAll Whether or not to restore journal entries for all globals in the directory; not case-sensitive and required.
Y — restore journal on all globals in this directory
N — specify globals for journal restore in globals list
Globals A list of globals separated by commas for journal restore. Only used if RestAll is N. If the list of globals is large, you can enter the remaining global names on the next line but you must specify the directory name again followed by N and then the list of globals.
Examples of different records:
DUA0:[TEST1],Y
DUA1:[TEST2],N,GLO1,GLO2,GLO3
DUA1:[TEST2],N,GLO4,GLO5,GLO6
DUA1:[TEST3],n 
The last record could also be completely omitted if you do not want to restore the journal for that directory.
Requirements of the file indicated by dirlist:
Argument Description
SourceDir Name of the directory to restore
TargetDir Directory name to which to restore; omit if restoring to same as source directory.
CreateDir Whether or not to create the target directory if it does not exist.
Y — create the target directory
N — do not create target directory
Examples of different records:
DUA0:[TEST1] 
DUA1:[TEST2],DUA1:[TEST2] 
DUA2:[TEST3],DUA2:[TEST4],Y 
DUA2:[TEST5],DUA2:[TEST6],N 
The following return codes are possible from calling these functions:
Return Code Description
3 No errors; successful completion
-1 Cannot open input device (device to restore from)
-2 Volume label does not match label in backup history
-3 Backup/Restore already in progress
-4 Invalid device for reading selection criteria (for selective restore of directories)
-5 Invalid journal restore option
-6 Invalid journal file or file for selection criteria for journal restore cannot be opened
Estimate Backup Size Using ^DBSIZE
Immediately before performing any backup, estimate its size using the ^DBSIZE utility, which estimates disk space needed for the backup.
The utility ^DBSIZE provides an estimate of the size of the output created by a Caché backup. It is only an estimate, since there is no way of knowing how many blocks will be modified once the backup has been started. You can obtain a more accurate estimate by preventing global updates while running ^DBSIZE, and then doing your backup before allowing global updates to resume.
You can estimate the size of backups in two ways:
Note:
A database must be in the list of selected databases to be backed up before you can evaluate it with ^DBSIZE.
Run DBSIZE Interactively
The following procedure describes the steps necessary to run ^DBSIZE interactively:
  1.  Do ^DBSIZE
  2. Caché displays the DBSIZE main menu:
                  Incremental Backup Size Estimator
    
    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
    1=>
  3. Select the type of backup for which you want an estimate: full, incremental, or cumulative incremental.
  4. At the “Suspend Updates? Yes=>” prompt, either:
    Press Enter to suspend updates so that you get a more accurate estimate;
    or
    Enter No to continue updates
  5. Examine the results that are displayed.
    First, DBSIZE shows you how many Caché blocks you need to do the type of backup you selected, for:
     
    Suspend Updates?  Yes=> n
     
                                             In-Use
         Directory                           Blocks
     
    c:\cachesys\mgr\                             983
    c:\cachesys\mgr\cachelib\                   5320
    c:\cachesys\mgr\docbook\                    6137
    c:\cachesys\mgr\samples\                     687
    c:\cachesys\mgr\user\                         45
                                            --------
         Total Number of Database Blocks:      13172
     
    For a disk file:
         Total size including overhead:
              52960 512-byte blocks = 27115520 bytes
     
    For Magnetic Media:
         Total Number of 16KB Blocks including overhead of backup
              volume and pass labels:  1655
    
Next, DBSIZE provides information about backup to disk file (for Windows 95/98, Windows NT and UNIX) or RMS file (for OpenVMS). If the directories to be backed up include any long strings, you see separate lines for standard and long block sizes.
 
For a disk file:
     Total size including overhead:
          52960 512-byte blocks = 27115520 bytes
 
For an RMS file:
  Total Number of 512 Blocks including overhead of backup
       volume and pass labels:  24064
     Pre Allocation quantity is: 32016
Finally, DBSIZE provides information about the amount of space used if the backup is made to magnetic tape.
For Magnetic Media:
     Total Number of 16KB Blocks including overhead of backup
          volume and pass labels:  1655
Use the DBSIZE Function
You can also call ^DBSIZE from a routine. To do so, you use the following function:
$$INT^DBSIZE(backup_type)
Important:
The values of backup_type differ from the option values running ^DBSIZE interactively.
Values of backup_type
backup_type Description
1 Incremental backup
2 Full backup
3 Cumulative incremental backup
For example to run a full backup:
%SYS>w $$INT^DBSIZE(2)
13178^5
The returned value is two numbers separated by a caret (^). In this example, the returned value 13178 is the total estimated size of the backup, in blocks; the returned value 5 indicates the number of databases to be backed up.
%SYS>w $$INT^DBSIZE(1)
996^5
%SYS>w $$INT^DBSIZE(3)
996^5
%SYS>
 
%SYS>w $$INT^DBSIZE(1)
95^3^950272^16^1013760^1980^1980
%SYS>w $$INT^DBSIZE(2)
2620^3^22390784^377^22302720^43560^43560
%SYS>w $$INT^DBSIZE(3)
95^3^950272^16^1013760^1980^1980
%SYS>
 
Sample Backup Procedures
Caché Backup on UNIX
Caché Backup on OpenVMS
Incremental Backup on UNIX
Schedule Backups with Task Manager
External UNIX Backup Script
Caché makes it easy to integrate with such utilities. The following is an example of a UNIX procedure:
  1. Clear the list of database blocks modified since the last backup. This synchronization point later allows you to identify all database blocks modified during the backup. Call the application program interface (API), CLRINC^DBACK("QUIET"), in the backup script; this completes instantly.
  2. Using your preferred backup utility, copy the CACHE.DAT files which may be in use.
  3. Perform an incremental backup of the blocks modified by users during the backup. This should be an output sequential file. Since it is likely to be a small set of blocks, this step should complete very quickly. Call the API, BACKUP^DBACK(), in the backup script.
    Important:
    The journal file should be switched at this time.
  4. Copy the incremental file to the backup save-set, using your preferred UNIX command.
The following is an abbreviated example of the cbackup script:
../bin/cuxs -s . -U "" -B << cleanup
s x=\$\$CLRINC^DBACK("NOISY") 
i x s x=\$\$BACKUP^DBACK("","E","UNIX Backup via call_os_backup","","","") 
o "cback_temp":"WAS" u "cback_temp" w x c "cback_temp" 
h 
cleanup 

CLRINC and BACKUP("","E") are performed in one Caché session.
UNIX Backup and Restore
You should perform a UNIX level backup of your system periodically. You can perform a UNIX level backup either from the UNIX prompt or using the UNIX/Caché backup facility cbackup discussed below.
Using UNIX Backup Utilities
Use a UNIX backup utility in place of Caché Backup in the following situations:
The following table lists UNIX utilities you may find useful for these types of backups.
UNIX Backup Utilities and Commands
Utility/Command Function
cp and mv (copy and move) Copies or moves the given file or files to a different file, directory, or file system. Example: move the manager's directory (and the binary files in /usr/bin) to another directory, using the following command: #mv /usr/cache/* /usr/cache.old/*
tar (tape archiver) Standard UNIX command to copy files and directories, extract files from tape, and list the files on a tape. Produces more portable output than cpio or dump.
cpio In conjunction with the find command, performs backups similar to the tar command.
dump Performs complete system backups.
bru A third-party backup and restore utility. Before using it on your system, verify that it works properly and meets your requirements.
cbackup Utility
A UNIX utility called cbackup allows you to back up your Caché databases using a system-level backup while automatically updating your Caché internal incremental backup. Using cbackup allows you to use the backup tools available on your operating system to back up your Caché databases and synchronize the bitmap information with the Caché internal incremental backup facility. This updates your Caché backup history so that you can use cbackup for full backups and the Caché Backup utility for incremental backups.
On Caché for UNIX, you must initiate all restores after backup interactively through the BACKUP utility.
Note:
The cbackup utility is called from the shell environment. The backup utility halts Caché while it performs the backup and then restarts it.
To enable journaling you must first set up the call_os_backup file to choose your UNIX backup utility. The call_os_backup file is automatically installed in your system manager directory. The example below uses tar as the backup utility.
:
# InterSystems Corporation
#
# File: call_os_backup
#
# This is a template for the user-specific backup procedure.
# It should backup Cache database files from a directory list contained in
# the cback_dir_list file, which is generated by the cbackup script that
# calls this one.
#
# Do not forget to include database extension files if any!
#
# Variable 'backstatus' should be set to 1 for success 
#                                        0 for failure
#
# For example:
#
#     sed -e "s/\/$//" cback_dir_list > cback_tar_list
#     if tar cvfF /dev/rmt0 cback_tar_list
#     then backstatus=1
#     else backstatus=0
#     fi
To use tar as your UNIX backup utility remove the comment marks from the last five lines above. If you want to use a different utility, use the form presented above to set up the backup utility.
#
echo "This message is from the call_os_backup script, which should contain a"
echo "user-defined backup procedure to backup Cache database files according"
echo "to a list of directories stored in cback_dir_list."
echo ""
echo "   !!! Do not forget to include database extension files if any !!!"
echo ""
echo "   Variable 'backstatus' should be set to 1 for success"
echo "                                          0 for failure"
#
backstatus=1
#
exit $backstatus
Performing Both Caché and System-level Backups Using cbackup
  1. Be sure Caché is running and that you are in the manager's directory.
  2. Enter the Backup Menu to ensure that you have selected all the directories you want to back up.
  3. Halt out of Caché to return to the UNIX shell.
  4. Type cbackup at the UNIX shell prompt. You will be prompted for confirmation of the directories to be backed up. The cbackup script automatically shuts down Caché and activates the call_os_backup script which performs the backup.
OpenVMS Backup
To perform OpenVMS BACKUP you must shut down Caché. The OpenVMS backup copies entire CACHE.DAT and CACHE.EXT files.
CACHE.DAT and CACHE.EXT files created with either the Caché Database utility or the character-based MSU utility are RMS files. Thus, they can be backed up and copied using OpenVMS utilities, such as BACKUP.
You can defragment your Caché databases by using the OpenVMS BACKUP utility monthly to backup and restore your CACHE.DAT and CACHE.EXT files.
You can use the OpenVMS BACKUP utility to perform your weekly full backup as part of your strategy to ensure the physical integrity of your database. OpenVMS BACKUP provides greater redundancy and error checking than Caché backup. As a result, it is more proficient at recovering from tape errors.
The disadvantage of OpenVMS BACKUP is that, normally, Caché must be shut down to run the OpenVMS BACKUP. However, you can overcome this disadvantage by doing a OpenVMS BACKUP while Caché is running and following it with an incremental backup. See Using CBACKUP.COM.
Running OpenVMS BACKUP for a Caché Database
If you are using the OpenVMS BACKUP utility by itself, rather than in conjunction with Caché incremental backup as in the CBACKUP.COM example file, use this procedure:
  1. Have users log off the system and set OpenVMS interactive logins to zero.
  2. Stop Caché using the ccontrol stop command procedure.
  3. Use OpenVMS BACKUP to back up the system.
  4. If you are doing the backup to defragment your files, use the Restore option of the utility.
  5. Start Caché using the ccontrol start command procedure and resume operation.
  6. Enable OpenVMS logins.
  7. Record this full backup in the Management Information option of the Caché BACKUP Utility.
Using CBACKUP.COM
InterSystems supplies a command procedure, CBACKUP.COM, which provides a model of how to use entry points in Caché backup routines to perform a backup while Caché is running. This command procedure gives you examples of various combinations of OpenVMS and Caché backups.
CBACKUP.COM is loaded into the CACHESYS directory during Caché installation from the file CBACKUP_PROTO.COM on the distribution tape.
CBACKUP.COM checks that the process which is executing it meets one of the following three criteria:
This privilege is required because CBACKUP.COM uses the /IGNORE=INTERLOCK qualifier in the OpenVMS BACKUP command. If the process does not meet one of the criteria, an error message is printed and CBACKUP.COM terminates.
CBACKUP.COM carries out these actions:
  1. Performs the OpenVMS backup.
  2. Records the date, time, and a brief description of the OpenVMS full backup in the Caché Backup History. This information is used later when you request a restore.
  3. Runs a Caché incremental backup.
    InterSystems recommends that you examine this procedure in detail, modify it as necessary, and use it if you wish to use OpenVMS BACKUP or any entry points to Caché Backup.