backupAllDbFiles

backupAllDbFiles(backupDir:       String;
                 includeSysFiles: Boolean;
                 verifyFiles:     Boolean;
                 compressFiles:   Boolean;
                 overwriteFiles:  Boolean;
                 quiesce:         Boolean;
                 droppedFiles:    DbFileArray input) updating;

The backupAllDbFiles method of the JadeDatabaseAdmin class initiates a backup of all physical database files, optionally excluding system files, to the directory specified in the backupDir parameter. (The backup directory must be a valid directory that is relative to the server.)

Set the includeSysFiles parameter to false if you do not want to include system files in your backup process (that is, files categorized by Kind = DbFile.Kind_System). For details about the kinds of database files that you can back up, see the DbFile class kind property or "DbFile Class Constants", earlier in this chapter.

For the majority of database backups, it is not necessary to back up system files, as they are not updated in development or runtime systems and can be shared by multiple JADE environments (by using the SystemFileDirectory parameter in the [PersistentDb] section of the JADE initialization file). System files are updated only when the RootSchema or JADE patch files are loaded by using the Schema Load utility. (For details, see the JADE Schema Load User's Guide.)

Set the verifyFiles parameter to true if you want the backed up file checked, or verified. In a checked file backup, objects are read using the database access routines and object caching mechanisms, and at the same time, a verification of the data and indexes is performed. The verification performs various consistency checks similar to a database certify, to ensure the integrity of the backup. Furthermore, additional checksum information is added to the backup, to allow restore operations to verify the integrity of the backup as the data is restored.

Set the compressFiles parameter to true if you want to compress data on the fly as it is backed up. You can compress data in a checked or an unchecked backup.

Set the overwriteFiles parameter to true if you want to allow file backups to overwrite existing files in the destination backup directory. When this parameter is false, an exception is raised if an existing file is detected.

Use the quiesce parameter to allow a quiesced read-only backup transaction to be specified. When you set this parameter to true, the database is placed in a quiescent state by first allowing current active transactions to be completed, flushing modified buffers for cache to the stable database. In this mode, physical database files contain all committed updates to the database, and the files are opened in read-only mode with shared read access allowing external backup processes to safely copy database files.

In the quiescent mode, updating transactions are not permitted and attempts to execute database transactions raise a database exception. When a backup is performed in the quiescent mode, the physical database files are guaranteed to contain all database updates and a quiesced backup does not require backup recovery.

Set the quiesce parameter to false to allow updates during the backup process. When restoring a database backed up fully online (that is, this parameter is set to false), the restoration process requires the recovery of backed up transaction journals. A backup recovery is required after restoring files that were fully backed up online (that is, the quiesce parameter was set to false).

The droppedFiles parameter specifies an array of the database files that are not backed up.

The following example shows the use of the backupAllDbFiles method.

backupDatabase();
vars
    dba : JadeDatabaseAdmin;
    droppedFiles : DbFileArray;
    file : DbFile;
    includeSysFiles, verifyFiles, compressFiles, allowOverwrite : Boolean;
    quiesce : Boolean;
    backupDirectory, title, msg : String;
begin
    create dba transient;
    create droppedFiles transient;
    backupDirectory := "n:\jade\backup";
    includeSysFiles := false;   // Exclude system files from backup
    verifyFiles     := true;    // Verify data during backup
    compressFiles   := false;   // Don’t perform on-the-fly data compression
    allowOverwrite  := true;    // Overwrite existing files in directory
    quiesce         := false;   // Don't quiesce => full online backup
    dba.backupAllDbFiles(backupDirectory, includeSysFiles, verifyFiles,
                    compressFiles, allowOverwrite, quiesce, droppedFiles);
    // The backup completed without exceptions
    title           := "Database Backup Complete";
epilog
    if process.isInExceptionState then
        // A fatal exception has occurred during the backup, the activated
        // exception handler aborted the current action - report the failure
        title       := "Database Backup Failed";
    endif;
    // Report missing files (only valid if they have never been created)
    if droppedFiles.size > 0 then
        msg := 'The following files were not backed up :' & CrLf;
        foreach file in droppedFiles do
            msg := msg & file.name & '.dat' & CrLf;
        endforeach;
    endif;
    app.msgBox(msg & Cr, title, MsgBox_Exclamation_Mark_Icon + 65536);
    delete dba;
    delete droppedFiles;
end;