BC-BRI BACKINT Interface for Oracle Databases

BC-BRI BACKINT Interface for Oracle Databases

Interface Specification: Oracle Database Administration

TABLE OF CONTENTS

INTRODUCTION TO BR*TOOLS ... 4

BR*Tools for Backup, Restore, and Recovery ... 4

BRBACKUP ... 5

BRARCHIVE ... 6

BRRESTORE ... 6

BRRECOVER ... 7

BACKINT Interface to External Backup Tools... 8

Link to the Computing Center Management System ... 8

I: BACKINT INTERFACE FOR ORACLE DATABASES ... 11

Interface Functions ... 11

Backup Function ... 11

Restore Function ... 11

Inquire Function ... 11

Formal Definition of the Interface Program for the Backup Utility ... 12

Basic Parameters ... 12

Parameter <type> = file ... 13

Parameter <type> = file_online... 13

Control Parameters ... 15

Input File Contents ... 15

Output File Contents ... 16

Variable Definition ... 16

Input/Output File Correlation ... 17

BACKINT Return Code ... 17

Examples ... 17

Known Problems and Additional Information ... 19

Online Backups with Function Type ... 19

BACKINT Definition ... 19

Configuration and Function of the External Backup Tool ... 20

Support for Offline Backups with the Parameter file_online ... 20

II: EXTENSIONS TO BACKINT INTERFACE ... 21

Aims ... 21

Concepts ... 21

Prerequisites ... 21

Formal Description of Extensions ... 22

New Values volume and volume_online for BACKINT Option -t (type) ... 22

New Values mount and dismount for BACKINT Option -f (function) ... 23

New BACKINT Option –n (negative) ... 23

Extended Output of Information on the Backup Utility Volume ... 24

User-Defined Additional Options for BACKINT ... 25

Optional Progress Information Generated by BACKINT ... 25

Optional Database Suspend and Resume for Disk Split ... 25

URL for Additional Backup/Restore Information ... 26

Additional Environment Variables for BACKINT ... 26

backup_dev_type = util_vol | util_vol_online ... 27

util_vol_unit = disk_vol | sap_data | all_data | all_dbf... 27

util_vol_access = none | copy | mount | both ... 28

util_vol_nlist = (<nfile_name1>, <nfile_name2>, …) | no_check ... 28

util_vol_options = “< backint_volume_backup_options>” ... 29

util_options = < backint_options> ... 29

util_vol_path = <backint_volume_backup_directory>... 29

util_path = <backint_directory> ... 29

Copying of Snapshot or Clone Files to Tertiary Storage ... 29

Examples of Backup, Restore/Recovery and Verify Procedures... 30

Complete Online Backup of the Database with Verification on Database Host with “mount” Access ... 30

Complete Offline Backup of the Database with Verification on Database Host with “copy” Access ... 30

Complete Recovery with BRRECOVER after the Loss of a Database File on Database Host ... 31

Verification of a Disk-Volume Backup with BRRESTORE on Backup Host with “mount” Access ... 31

Compatibility and Final Comments ... 32

APPENDIX A: QUICK TEST ENVIRONMENT ... 33

Installing the Oracle Database ... 33

Creation of Database Objects ... 33

Installation of BR*Tools ... 34

Installation of BACKINT ... 34

Users, Privileges, and Environment ... 34

Installation Information ... 35

Testing Information ... 36

Complete Test Sequence ... 36

APPENDIX B: BACKINT INTERFACE TEST ... 37

INTRODUCTION TO BR*TOOLS

The database server plays an important role in the server technology of SAP Business Solutions. In response to customers requesting support for administrative tasks, SAP has included several database administration tools in the standard SAP System package.

These tools can be used, for example, for backup and recovery. For a long time, only basic backup programs (for example dd, cpio, tar) were available for open operating systems like UNIX. These are not suitable for backing up a relational database because they do not:

 Deal with special problems that might occur during database backup

 Provide tape management

Therefore, SAP offers its own backup programs. These tools enable you to easily and completely back up the SAP system, so that your system runs smoothly. There is also a BACKINT interface that integrates the most common client/server backup programs.

SAP provides the following BR*Tools for Oracle database administration:

 BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER Database backup, restore and recovery

 BRCONNECT

 BRSPACE (database statistics, database check, cleanup logs and traces)

Database administration (for example, database startup or shutdown, tablespace extension, space management, reorganization. You can access the entire functionality of BR*Tools using a graphical user interface (BRGUI) or a character interface (BRTOOLS).

For more information, see “References” [page 37]. The following platforms are supported:

HP-UX, AIX, Solaris, Windows, Linux

We have recently introduced an optional extension to the Backint interface, available in BR*Tools 7.10.

For more information, see “II: EXTENSIONS TO BACKINT INTERFACE” [page 21].

There is only one small extension affecting the standard BACKINT specification. This concerns the $SAPSWITCH/%SAPSWITCH environment variable in specifying the location of the .switch files. For more information, see “Parameter <type> = file_online” [page 13].

BR*Tools for Backup, Restore, and Recovery

BRBACKUP and BRARCHIVE are command-line programs for data backup, which you can also schedule in the background. Online help provides information on available options. Both programs issue messages in English or German.

Backups are based on the following programs:

 cpio, dd in a UNIX environment (for a backup to disk: cp, dd)

 MKS1-cpio, MKS-dd for Windows (for a backup to disk: copy, MKS-dd – already deprecated)

1

 External backup programs accessed using the BACKINT interface program – see figure “Backup of the Oracle Database Using an External Backup Tool”[page 8]

 Oracle Recovery Manager (RMAN)

Oracle Backup (Native) Using cpio or dd

Oracle Database

BRARCHIVE

BRRECOVER

BRBACKUP

BRRESTORE

Detail and summary log Detail and summary log

Data files Online redo log files Offline redo log files Control files Backup Media cpio/dd serial cpio/dd parallel Backup Media

BRBACKUP and BRARCHIVE log all actions in the file system and database tables, and also save backup logs and profiles to backup media.

BRBACKUP and BRARCHIVE enable comprehensive volume management. To use the functions provided, you must initialize the volumes with BRBACKUP or BRARCHIVE to ensure that they include an SAP-specific label. You cannot overwrite volumes that have not been released for use if the label specifies that they are still locked.

You can determine the names and number of volumes required for BRBACKUP or BRARCHIVE in advance using the query mode, without starting a backup. The programs let you verify completed backups in detail. You can use BRRESTORE and BRRECOVER to restore and recover an Oracle database that was backed up using BRBACKUP and BRARCHIVE.

BRBACKUP

BRBACKUP enables an online or offline backup of the control file, of data files in some or all tablespaces and, if necessary, of the online redo log files. See figure “Oracle Backup (Native) Using cpio or dd” [page 5]. BRBACKUP also saves the profiles and logs relevant to the backup. In addition to the actual backup, BRBACKUP also:

 Automatically changes the state of the database (opened or closed), depending on the type of backup (online or offline)

 Checks the status of files

 Sets the tablespace backup status (BEGIN / END BACKUP)

 Optimizes data distribution on the backup media. The algorithm for distribution is specially adapted to the requirements of a database backup (backing up a small number of large files). Data distribution depends on whether you perform a serial or parallel backup.

 Uses software compression, if this option is set.

 Saves to hardware compressing tape devices, taking into account previously determined compression rates.

During a backup, BRBACKUP starts another tool, BRCONNECT, which makes sure that the database status required for the online or offline backup remains unchanged during the backup.

You can also back up specific files or directories. However, a backup of a directory only includes the files located in the root of the directory without any subdirectories. This enables you to back up all SAP objects that are not part of the database (for example, programs, SAP start profiles, selected logs, and so on). For more information, see “References” [page 37].

BRBACKUP is not designed to back up complete file systems (that is, systems with many small files and directories).

BRARCHIVE

BRARCHIVE lets you back up the offline redo log files. These are the online redo log files saved to the archiving directory by Oracle. See figure ““Oracle Backup (Native) Using cpio or dd” [page 5]. BRARCHIVE also saves all logs and profiles relevant to the backup. It supports tapes and disks as storage media. We recommend backing up offline redo log files because:

 In the event of failure, a consistent database status can only be recovered if all the relevant redo log files are available.

 The database system of a productive SAP System has to run in ARCHIVELOG mode (to prevent overwriting online redo log files not yet saved). To protect the archive directory against overflowing, it must be emptied regularly.

 An online backup of data files is of no use if the related redo log files are missing. Therefore, it is necessary to back up the offline redo log files generated during the online backup immediately after running BRBACKUP.

For security reasons, BRARCHIVE in native mode (with cpio or dd) offers duplicate archiving of offline redo log files – redundant serial or parallel archiving is possible. Serial duplication is also available for BACKINT. Using the logs, BRARCHIVE can ensure that redo log files are not deleted before they have been backed up and that these files are saved either once or twice.

BRARCHIVE lets you continuously back up offline redo log files. This means that the backup directory, where Oracle stores the offline redo log files, can be kept clear by continuously backing up and then deleting current redo log files.

BRRESTORE

BRRESTORE lets you restore files of the following type:

 Database data files, control files, and online redo log files saved using BRBACKUP

 Offline redo log files backed up using BRARCHIVE

 Non-database files saved used BRBACKUP

You can specify files, tablespaces, complete backups, log sequence numbers of redo log files, or the position of a file on tape. BRRESTORE automatically determines the corresponding backup tape and the position of the files on the tape. BRRESTORE checks whether the required free disk space is available to allow the files to be restored and then restores the directory and link structure automatically. Directory $SAPDATA_HOME and mount points sapdata<n> must exist.

BRRECOVER

BRRECOVER offers menu options for restore or recovery specially designed to reflect user needs. BRRECOVER can:

 Recover the database to the current state after media error in several files, for example, due to a disk failure

 Restore the entire database for a point–in–time recovery or reset the database to a previous state BRRECOVER evaluates the backup logs to decide whether the specified recovery can be performed using the selected backups. For example, for a point-in-time recovery, BRRECOVER determines whether any actions that would prevent the recovery have taken place between the time of the backup and the selected recovery end time. If BRRECOVER cannot perform a recovery, it rejects the selected backup or the specified recovery procedure. Data can only be recovered automatically using BRRECOVER if BRBACKUP and BRARCHIVE (in native mode or with the BACKINT interface) were used for the backup. In this respect, the SAP tools BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER function as an integrated solution:

Integrated Solution for Backup, Restore, and Recovery

Control files Data files Online redo log files Offline redo log files

Backup Media

Restore and Recovery Detail and summary log Detail and summary log

BRRESTORE

BRBACKUP

BRARCHIVE

BRRECOVER

Detail and summary log

Data files Online redo log files

Offline redo log files Control files

BACKINT Interface to External Backup Tools

SAP BR*Tools can call the BACKINT interface program so as to communicate with an external backup program:

Backup of the Oracle Database Using an External Backup Tool

BACKINT BACKINT BACKINT BACKINT BRBACKUP BRARCHIVE BRRESTORE BRRECOVER Oracle database

SAP tool

Interface program

External backup /

restore program External BACKUP server Database files Offline redo log files

Media

BR*Tools are responsible for all database-related tasks. For backup and restore, they send requests to the BACKINT interface. BRRECOVER can request restore of profile and log files in the event of disaster recovery.

BACKINT is generally implemented and sold by the vendor of the external Media Management Software (MMS). SAP is responsible for defining BACKINT and guarantees the functionality of BR*Tools.

We recommend using BACKINT to implement a company-wide, uniform backup strategy. A major advantage is that it allows easy database administration using BR*Tools, particularly for database recovery.

Link to the Computing Center Management System

The Computing Center Management System (CCMS) – see “References” [page 37] – supports the use of BR*Tools with the following functions:

 Scheduling of an online backup with BRBACKUP

 Starting an offline backup with BRBACKUP

 Starting offline redo log backup with BRARCHIVE

The same functions are available when using BRBACKUP and BRARCHIVE with the BACKINT interface. The DBA Cockpit in CCMS lets you display the following:

 An overview of all backups performed using BRBACKUP or BRARCHIVE – see figure “Backup Overview in DBA Cockpit” [Page 9] below.

 All details – see figure “Backup Details in DBA Cockpit” [page 10] below, including the action runtimes and the amount of data processed

I: BACKINT INTERFACE FOR ORACLE DATABASES

The link from SAP BR*Tools to the external backup and restore program is based on the interface program BACKINT: see figure “Backup of the Oracle Database Using an External Backup Tool” [page 8] above. BACKINT processes the requests for backup, restore, and inquire, and executes them using the

corresponding backup tool. If the Media Management Software (MMS) is a client/server program, BACKINT communicates with the server program running on the backup server.

Interface Functions

The BACKINT interface supports the following functions (see figure “Backup of the Oracle Database Using an External Backup Tool” [page 8] above):

 Backup

 Restore

 Inquire

In all cases, the mandatory user ID (UID) option is used as an identifier for the SAP database. After a function has been executed, the interface program always returns an integer return code indicating whether the call was successful.

The user ID plays a significant role during a database copy. In this case BRRESTORE can request a restore of a backup with a given user ID on another server.

Backup Function

This defines a backup request including all files specified in a list. If the backup request cannot be processed completely, the interface program informs the user which files have been backed up successfully (partial backup). MMS determines the sequence in which the files are saved. On return, MMS generates a backup ID (BID) for each saved file, clearly identifying the backup. A backup file is uniquely identified by:

 User ID

 Backup ID

 File name

Restore Function

This is used to pass a restore request to MMS, consisting of a user ID (UID), backup ID (BID), a list of files to be restored, and a list of directories where files should be created. The last parameter is optional. If it is not set, the file is restored to its original location. If the backup ID is not set, the last backup of the related file is used. The return information indicates which files were restored successfully and which backup IDs were used.

Inquire Function

This provides information about the backups managed by the Media Management Software (MMS). This function is called using the UID, BID, and the file name (the last two parameters are optional). If both optional parameters are specified, the system checks whether this file was saved with a specific BID. If the BID is not set, a list of available backup IDs (BIDs) is provided, including the specified file. If a file name is not specified, a list of files belonging to a specific BID is generated. If neither of the two parameters is set, a list of available backups with BIDs is generated. In general, the BID does not always identify a backup run, although this is normally true. It can also identify the backup of a single file or a group of files.

The BACKINT interface does not distinguish between Oracle single instance and Real

Application Cluster (RAC) installations. Based on this distinction, BR*Tools alone executes the required database handling.

Formal Definition of the Interface Program for the Backup Utility

BACKINT uses a call interface at command line level with the following syntax:

backint -u <user_id> [-f <function>] [-t <type>] [-p <par_file>] [-i <in_file>] [-o <out_file>] [-c]

You can find descriptions of the parameters user_id, function, type, par_file, in_file

,

out_file in the sections “Basic Parameters” [page 12] and “Control Parameters” [page 15].

In addition to the command line options, the interface also supports some environment variables set by BR*Tools before BACKINT is called:

Environment Variable Value Description

BI_CALLER BRBACKUP

BRARCHIVE BRRESTORE BRRECOVER

BACKINT is called by BRBACKUP, BRARCHIVE, BRRESTORE, or BRRECOVER

BI_BACKUP FULL

PARTIAL ARCHIVE

Full database backup, partial database backup, or offline redo log backup

BI_REQUEST NEW

OLD

First call or following BACKINT calls within a run of BRBACKUP, BRARCHIVE, BRRESTORE, or BRRECOVER.

BACKINT can be called multiple times during one run of an SAP tool.

BR*Tools sets the environment dynamically (using putenv), and BACKINT, as the child process, inherits these variables (using getenv) and can use them to control further processing.

For example, we recommend that you do not change the order of the offline redo log files (BI_BACKUP = ARCHIVE) during the backup. The best practice is to back up the offline redo log files in the order specified in the input file (see option –i). This lets BRARCHIVE empty the archive directory as quickly as possible.

Basic Parameters

Option Parameter Description Default

-u <user_id> _{<user_id>}

_(UID)

Backup tool user, normally database instance name (ORACLE_SID)

None

-f <function> <function>: backup|restore|inquire Type of operation – see figure “Backup of the Oracle Database Using an External Backup Tool” [page 8] above

backup

-t <type> <type>: file|file_online

Backup type: backup of individual files, directories, character special devices

-c Unattended mode (no interaction with operator possible)

Attended mode

Parameter <type> = file

Backup type file for functions backup, restore, inquire (see table above) is the default for handling data files and directories as well as character special devices (that is, raw disks).

Oracle assumes one file per raw disk. Such a disk cannot be shared among different files. Therefore, BACKINT is used in the same way as for regular files, except that all the file names in the input file are character special device files, each followed by the file size used by Oracle. The minimum backup should include at least this amount of data starting from the beginning of the partition. The file size is only specified if BACKINT is called for the backup function.

On some platforms Oracle files do not start on raw partitions from byte 0, but rather with a certain offset (for example, 4 KB for AIX).

This offset, used for control data of the logical volume manager, must be taken into account when backing up files from raw partitions. The offset must be skipped or added to the file size set in the input file. In addition, while restoring database files to raw partitions, the control information at the beginning of the partition must not be overwritten – it must be skipped. When directories are saved, only objects at the root of the directory are saved, not the contents of the subdirectories. If the directory object is a subdirectory, only the definition is saved, not the contents of the subdirectory. BRBACKUP expands the directory structure itself if necessary. An error should be reported if such a directory backup is not supported by the Media Management Software (MMS).

BACKINT has to check if the name stands for a file, directory or raw partition. Since profiles and logs remain in a file system and are backed up, the list of objects can be mixed.

Parameter <type> = file_online

The backup type file_online allows BRBACKUP to switch the tablespace into BEGIN / END BACKUP mode only when backup of the related files actually occurs.

Backup type file_online uses the following files:

File UNIX:

File in $SAPSWITCH if set, otherwise in

$ORACLE_HOME/sapbackup

Windows:

File in %SAPSWITCH% if set,

or %SAPBACKUP% if set, otherwise in %SAPDATA_HOME%\sapbackup

Switch-list .switch.lis .switch.lis

Switch-semaphore .switch.sem .switch.sem

Switch-log .switch.log .switch.log

Note the location of the .switch.* files defined in the column headings of the above table. Communications are described by specifying the tasks for BACKINT and BRBACKUP.

BACKINT creates a switch-list file whenever it wants to back up a file (#BACKUP) or whenever it wants to indicate that a backup is finished (#END):

#BEGIN | #END <file1> [#BEGIN | #END <file2>]

... ...

BACKINT must not send multiple #BEGIN / #END messages to BRBACKUP (actually, to BRCONNECT) for the same file. If you need to restart a file backup during a backup session, you must do this within a single #BEGIN – #END interval.

You can put multiple lines into a single switch-list file, mixing #BEGIN and #END lines. Therefore, it is a good idea to put as many files into a single switch-list file as possible. Normally, it is best to put the first files of all parallel BACKINT backup processes in the first switch-list file. During the backup, when BACKINT is about to back up the next file, put both files, the previous one and the next one, into the switch-list file:

#END <previous_file> #BEGIN <next_file>

This lets BRBACKUP (actually, BRCONNECT) minimize the number of tablespace BEGIN/END BACKUP switches.

After the switch-list file has been created and closed, BACKINT creates the empty switch-semaphore file and waits – the wake-up period is determined by BACKINT, approximately 1 to 4 seconds – until this file has been deleted by BRBACKUP (actually, BRCONNECT).

It can take several minutes to put a tablespace into the backup state. Therefore, BACKINT should wait at least 20 minutes before reporting timeout and aborting processing.

After the switch-semaphore file has been deleted, BACKINT opens and reads the switch-log file. The operation is successful and BACKINT continues processing if it finds a single line in this file that includes: #SUCCESS

However, the operation has failed and BACKINT terminates with an error if it finds a single line that includes: #ERROR

All lines except those with the keywords #SUCCESS or #ERROR are copied to the output file (see -o option). BACKINT deletes the switch-log file after reading it.

Messages written to the output file should be flushed after each line.

BRBACKUP (actually, BRCONNECT) periodically checks if such a switch-semaphore file exists and sets the wake-up period.

If BRBACKUP (actually, BRCONNECT) detects a switch-semaphore file, it opens and reads the switch-list file, then issues and logs the appropriate begin/end backup statements in the switch.log file. After completion, it deletes the switch-semaphore file and the switch-list file. BACKINT is then allowed to proceed. BRBACKUP (actually, BRCONNECT) decides when to put a tablespace into BEGIN/END BACKUP mode by using a history of former requests. This is necessary because only BRBACKUP (actually, BRCONNECT) knows when any of the data files of one specific tablespace are backed up.

During a backup run, only one process can communicate with BRBACKUP (actually,

processes or sessions to back up the files, you must coordinate this through a master process (normally the BACKINT process) to avoid unpredictable results.

All handles to the switch files should be released (that is, closed) before giving up the hand-shake control to BRBACKUP (actually, BRCONNECT). This lets BRBACKUP (actually, BRCONNECT) delete these files without problems.

Control Parameters

Option Parameter Description Default Type

-p <par_file> <file>

Parameter file for backup utility containing parameters that determine the backup procedure – specific to the backup utility. The SAP tools specify the location of this utility parameter file in their own parameter file (parameter

util_par_file|util_vol_par_file), but they do not evaluate its contents.

none

-i <in_file> <file>

Text file that defines the objects of the function (backup, restore, or inquire). If this parameter is not set, data is read from the standard input.

STDIN See table “Input File Format

”

[page

15

].

-o <out_file> <file>

Output file for processing messages and the results of the executed function. If this parameter is not set, the messages are written to the standard output.

STDOUT See table “Output Message Format” [page 16].

Input File Contents

The contents of the input file <in_file> depend on the backup function:

Input File Format

Function Input Entries

backup Names of files and directories to be saved.

Character special file

<file1> [<file2>]

<special_file1> <size1> [<special_file2> <size2>] restore Names of files to be restored using BIDs:

#NULL: last backup

optional: use changed target directories or raw disks

<backup_id> <file1> [<dest_dir1>] [#NULL <file2> [<dest_dir2>]]

inquire Names of files and/or BIDs about which information is requested.

#NULL: no backup ID

See also table “Correlation of Input and Output Values for the “Inquire” Function”

#NULL

[<backup_id>] [#NULL <file1>]

[page 17].

<backup_id> Backup ID assigned by the MMS, passed on as a return value in connection with the backup function; can only be set in the input file using the restore and inquire functions.

For comments on the size of the raw partition to be backed up, see “Caution” on page 13.

When restoring the raw partition to a different one than the original, the <dest_dir> means the new raw partition, not the directory containing the special file.

Output File Contents

In addition to the messages with fixed format defined below, the file might contain other messages that are simply passed on to the user. If the output file is not specified, the output is sent to the standard output (STDOUT).

The contents of the <out_file> output file depend on the backup function:

Output Message Format

Function Successful Messages Error Messages backup #SAVED <backup_id> <file> [<backup_vol>] #ERROR <file>

restore #RESTORED <backup_id> <file> #NOTFOUND <file> #ERROR <file>

inquire #BACKUP <backup_id>

#BACKUP <backup_id> <file>

See also table “Correlation of Input and Output Values for the “Inquire” Function” [page 17].

#NOTFOUND <file> #ERROR <file>

Note the following for messages written to the output file:

 Messages should be flushed after each line

 Messages must not be longer than 1024 characters.

BACKINT should avoid writing any other lines starting with the character “#” to the output file. This can disturb the work of BRRECOVER tool, which is sensitive to such lines generated by BRBACKUP and BRARCHIVE. If needed, write such lines only to your own logs.

Variable Definition

All entries have a variable character format as described in the following table:

Type of Entries

Entry Description Type (maximum length)

<file> File, directory char(255)

<special_file> Raw device char(255)

<dest_dir> Directory char(255)

<size> File size in bytes char(16)

<user_id> User ID char(16) <backup_vol> Backup volume (for example, tape

label) – optional

char(10)

<backup_id> can be any character string up to a length of 16 not containing any white spaces.

Input/Output File Correlation

The contents of the output file for the inquire function depend greatly on the type of request. We can distinguish the following cases:

Correlation of Input and Output Values for the “Inquire” Function

Case Input Output

A BID and file name not specified (#NULL)

List of BIDs for UID sorted by creation date (most recent backup first). One list line consists of one BID. B BID specified, file name not

specified

List of BIDs and related files in the specified backup. One list line consists of the specified BID and one file name.

C BID not specified (#NULL), file name specified

List of BIDs related to the specified file, sorted by creation date (most recent backup first). One list line consists of one BID and the specified file name. D BID and file name specified BID and file name, if available, in the specified backup.

One list line consists of one BID and one file name. It should be only one line in the list.

BACKINT Return Code

BACKINT is called from BRBACKUP, BRARCHIVE, BRRESTORE, or BRRECOVER. All these programs expect BACKINT to return a code as described in the following table:

BACKINT Return Code

Return Code

Description

0 OK – All files were successfully processed without warnings 1 WARNING – But all files were successfully processed > 1 ERROR - Some or all files were not successfully processed

Examples

Below you can find examples for using BACKINT to back up and restore a SAP/Oracle database instance identified by SID = C11, assuming a file named dummy contains the file name:

/oracle/C11/sapdata1/user1i_1/user1i.data1

 Backup

Call BACKINT as follows for a backup:

/oracle/C11/dbs/initC11.utl -i dummy -o dummy.out

The output file dummy.out might look as follows:

********************* dummy.out *************************************** Program: backint

Parameters: Client node: RC1 Function: backup Input File: dummy Output File: dummy.out

Profile: /oracle/C11/dbs/initC11.utl Parallel sessions: 1

BKI0008I: Number of bytes to save: 0.012 MB. Backup started ...

#SAVED SAP___9409020458 /oracle/C11/sapdata1/user1i_1/user1i.data1 BKI0022I: Bytes saved so far: 0.012 MB (100.0%).

*********************************************************************** Only the line starting with the keyword #SAVED is interpreted by SAP programs as described in “Formal Definition of the Interface Program for the Backup Utility” [page 12]. The rest is normally copied to the log file of the SAP program.

 Restore

Restore the backup by setting the tag #NULL in front of the file name in dummy: #NULL /oracle/C11/sapdata1/user1i_1/user1i.data1

Call BACKINT as follows for a restore:

OS> backint -u C11 -f restore -t file -p

/oracle/C11/dbs/initC11.utl -i dummy -o dummy.out

The output file dummy.out might look as follows:

********************* dummy.out *************************************** Program: backint

Parameters: Client node: RC1 Function: backup Input File: dummy Output File: dummy.out

Profile: /oracle/C11/dbs/initC11.utl Parallel sessions: 1

BKI0032I: Number of bytes to restore: 0.012 MB. Restore process started ...

#RESTORED SAP___9409020458 /oracle/C11/sapdata1/user1i_1/user1i.data1 BKI0023I: Bytes restored so far: 0.012 MB (100.0%).

*********************************************************************** Only the line starting with the keyword #RESTORED is interpreted by SAP programs as described in “Formal Definition of the Interface Program for the Backup Utility” [page 12]. The rest is normally copied to the log file of the SAP program.

Perform the inquire by setting the tag #NULL in front of the file name in dummy (list of all backups in which this file was saved):

#NULL /oracle/C11/sapdata1/user1i_1/user1i.data1 Call BACKINT as follows for an inquire:

OS> backint -u C11 -f inquire -t file -p

/oracle/C11/dbs/initC11.utl -i dummy -o dummy.out

The output file dummy.out might look as follows:

********************* dummy.out ************************************** Program: backint

Parameters: Client node: RC1 Function: backup Input File: dummy Output File: dummy.out

Profile: /oracle/C11/dbs/initC11.utl Parallel sessions: 1

#BACKUP SAP___9409020458 /oracle/C11/sapdata1/user1i_1/user1i.data1 #BACKUP SAP___9409020450 /oracle/C11/sapdata1/user1i_1/user1i.data1 ***********************************************************************

Only the line starting with the keyword #BACKUP is interpreted by SAP programs as described in “Formal Definition of the Interface Program for the Backup Utility” [page 12]. The rest is normally copied to the log file of the SAP program.

In this example, two backups with different backup IDs were found. Generally, the backup ID includes a unique key that can consist, for example, of a class of objects and the time of the backup. This enables unique backup identification.

Known Problems and Additional Information

Online Backups with Function Type

In general, a problem can occur if you run a complete online database backup using BRBACKUP

BACKINTBACKUP utilityand perform large-scale data manipulation language (DML) operations at the same time. Since BRBACKUP needs to set all the tablespaces in BACKUP status at the beginning of the backup, a large number of redo logs is created. If you do not consider this, it might lead to an archiver stuck. One consequence is that BRBACKUP cannot complete the operation (that is, update of its database catalog, end BACKUP status).

To avoid this situation we recommend running BRARCHIVE with the -f option. If the problem is acute, use function type file_online.

BACKINT Definition

The file names transferred with the interface are always case–sensitive, independent of the operating system. This means that they have to be returned (in #SAVED, #RESTORED, #NOTFOUND, #ERROR, #BEGIN, and #END) in the same form they were when they were transferred to the input file. Pay special attention to this requirement when running on Windows because file names are normally not case-sensitive on this platform.

We recommend that BACKINT only uses the value of -u option <user_id> (not in combination with host name), to identify the calling client. SAP customers often use full database backup to create a system

copy on another host. This requirement to enable a restore on a host that differs from the backup host can also be indicated in another way, for example, by a special parameter in the parameter file.

Configuration and Function of the External Backup Tool

Experience has shown that some additional functions of the backup tool not subject to certification can be useful, particularly with respect to data security. We recommend that tool manufacturers offer the following functions:

 Backup verification

You can use this to make sure that all backup tapes are readable in the event of a recovery.

 Ability to create two copies of the offline redo log files

The backup tool should write the copies to separate tapes. The message (#SAVED), indicating that both files have been backed up successfully, should be output only once after both copies have been made. This procedure allows you to create two copies of the offline redo log files with one BRARCHIVE call, for example, brarchive –sd, BACKINT call using the environment variables BI_CALLER= BRARCHIVE. It also improves security for a database recovery.

 An acceptable INQUIRE query time. This often takes too long, up to several minutes. The result is to lengthen the recovery process and the system downtime, which is particularly critical when many offline redo log files have to be restored.

 Tape label checking

The backup tool should prevent unintentional overwriting of the tapes using a tape label and suitable locks.

Support for Offline Backups with the Parameter file_online

Starting with BR*Tools Release 6.10, the backup type file_online is also supported for offline backups. In this scenario, the database is stopped and started not before and after the BACKINT call, but duringthe BACKINT run. The database is:

 Stopped by the first #BEGIN message in the .switch.lis file

 Started again by the last #END message in the file

This procedure enables split-mirror and snapshot scenarios for offline backups to be fully implemented in BACKINT. The following shows a typical sequence:

1. BRBACKUP is started with the following parameters:

backup_type = offline and backup_dev_type = util_file_online

2. BRBACKUP starts BACKINT with the option -t file_online, without first stopping the database. 3. BACKINT passes the .switch.lis file to BRBACKUP (actually, to BRCONNECT), containing the

#BEGIN message for all files to be backed up.

4. BRBACKUP (actually, BRCONNECT) then stops the database and deletes the .switch.sem file. 5. BACKINT splits the disk and passes the .switch.lis file to BRBACKUP (actually, to BRCONNECT)

with the #END message for all files that are to be backed up.

6. BRBACKUP (actually, BRCONNECT) then starts the database and deletes the .switch.sem file. 7. BACKINT backs up the split files and passes the #SAVED messages to BRBACKUP.

II: EXTENSIONS TO BACKINT INTERFACE

Aims

The extensions to the BACKINT interface have the following aims:

 Better support of snapshot and cloning technology, which is increasingly becoming the industry standard

 Better methods to fully implement split-mirror disk technologies in BACKINT as an alternative to the support of the SPLITINT interface

 Enable use of BRRECOVER procedures for backup based on snapshot and cloning technologies The extensions support backups at the level of disk volume (volume backups), in addition to the backups at file level (file backups) available previously.

Support of these extensions is optional.

SAP Partners should clearly state in their BACKINT documentation whether and to what extent they support these extensions.

Concepts

By “disk volume” we normally mean a “logical volume” (file system / mount point / drive). This is the smallest unit that can be backed up with a snapshot or clone. Depending on the hardware and implementation, the smallest volume unit might also be bigger – for example, a “logical volume group”. The BR*Tools Parameter util_vol_unit defines which volume unit is used in a specific configuration (for more information, see “util_vol_unit = disk_vol | sap_data | all_data | all_dbf” [page 27] below).

In the event of a restore, the database files are normally reset to the state of a selected snapshot or clone, which is known as “snap-back” or “clone-back”. However, it’s often necessary to access such backups without overwriting the original files – for example, for verification purposes or to copy back into other directories. This type of additional access is controlled by the BR*Tools parameter util_vol_access. For more information, see “util_vol_access = none | copy | mount | both” [page 28]. This access normally uses a separate mount. But, depending on the implementation, the copying of individual files might be possible. To make the handling of disk volume backups easier, SAP recommends only complete backups. However, partial backups are still permitted. For partial backups BRBACKUP extends the list of database files to be backed up so that it always includes all database files on the selected volume units. See also “New Values volume and volume_online for BACKINT Option -t (type)” [page22].

Prerequisites

To create backups at disk-volume level, you need to meet the following prerequisites:

 All database files are in sub-directories of sapdata directories or in sapraw for raw disks.

 All online redo log files are in origlog or mirrlog directories, or in sapraw for raw disks.

 All control files are in sapdata, origlog, or mirrlog directories, or in sapraw for raw disks.

 Normally sapdata, origlog, or mirrlog are mount points (UNIX) or are on separate drives (Windows).

 There are no other non-database files in these directories.

 If database files from these directories are backed up at disk-volume level, no other files from other directories can be backed up in the same BACKINT call.

 It must be possible to back up files from other directories (for example, saparch, sapbackup, sapreorg) with a separate BACKINT call at file level in the same backup run.

Formal Description of Extensions

New Values volume and volume_online for BACKINT Option -t (type)

The backup function -f backup expects to back up all files of the disk volumes that are being backed up. The disk volumes to be backed up are defined in the file list of the input file. All disk volumes are backed up for which at least one file is in this list.

The input file still contains a list of file names, not a list of volume names.

BACKINT checks that the file list in the input file is complete. This list must contain all files located on the volume units that need to be backed up. If there are files on the volume units that are not in the list, these files are reported with the following error message in the output file:

#ERRFILE <file name>

Then BACKINT terminates immediately with an error exit code, without having performed a backup. Note the following about #ERRFILE errors:

 The fixed files, specified by the file system or by snapshot/clone software (for example, lost+found, .snapshot, and so on) are not reported in #ERRFILE.

 In the new option –n <nlist_file> there is an option to pass a text file to BACKINT. The text file contains a negative list of non-database files. For more information, see “New BACKINT Option –n (negative)” [page 23].

Also for these files, there is no #ERRFILE message, although they can be located on the backup volumes and are not specified in the input file.

If several hundred or thousand such files are found, only the first hundred should be reported.

This check is also made for the restore function, not for mount, dismount, and inquire functions. Particularly with the restore function only some of the files on the volume units might be requested for restore. Other files on the backed-up volume, which were in the backup request (that is, they were in the file list of the input file) and which are not on the negative list, are reported in the #RESTORED messages when the entire volume is reset with snap-back or clone-back. The recovery procedure (BRRECOVER) is prepared for all files on the volume units to be overwritten.

Files on the volumes to be overwritten, which are not in the restore request and were not in the backup request, and which are not on the negative list, are reported in the #ERRFILE messages. In this case, BACKINT terminates immediately with an error exit code, without having performed a restore.

The completeness check of the input list is deactivated if the option –n no_check is set. For more information, see “New BACKINT Option –n (negative)” [page 23].

The logic of –t volume_online has not changed. It remains like the logic of –t file_online. However, note that, when backing up a disk volume, all files from the input list on this volume should be written to a single .switch.list file.

The function –f restore to restore a disk volume expects that all files from the input list are reset by snap-back or clone-snap-back. The disk volumes to be reset are defined like the snap-backups. It is possible that other files on these disk volumes, which are not in the input list, are also reset. This happens when the original disk volumes are replaced by a snapshot or clone. However, if they need to be copied back to other locations – that is, when <dest_dir> is set in the input file – then individual files need to be copied from a volume backup, without overwriting other files. This is also true when <dest_dir> points to the original sub-directory. Since this functionality is optional, the backup utility does not have to support it. BR*Tools parameter util_vol_access specifies whether this functionality is available:

Not available: util_vol_access = none | mount

For more information, see “util_vol_access = none | copy | mount | both” [page 28], and example “Complete Offline Backup of the Database with Verification on Database Host with “copy” Access” [page 30].

Comments:

Theoretically, even with the current values of the –t option (file and file_online) the backup utility can internally use the volume logic (snapshots, clones). However, in must be able in the event of a restore to retrieve individual files from the backup without overwriting other files. Also in the opposite case (-t volume and –t volume_online) the backup utility can internally back up and restore single files instead of disk volumes. However, this is not especially worthwhile because it actually excludes the use of snapshot or cloning technologies and has no advantages.

New Values mount and dismount for BACKINT Option -f (function)

These new functions are particularly for the verification of the disk volume backups based on the snapshot or cloning technologies. On request from BRBACKUP the backup utility allows access to the backed-up files, using paths determined by the backup utility (mount). Depending on the implementation, these mounts might not be possible on the productive computer but instead on another computer, such as a backup server. During verification, BRBACKUP only accesses the backed-up files using the mounts in read-only mode. The input file for the mount function has the following format:

<backup_id1> <file1> <backup_id2> <file2> ...

The backup utility writes to the output file the sub-directories (or raw-disk paths) containing the backed-up files after the mount:

#MOUNTED <backup_id1> <file1> <sub_dir1> #MOUNTED <backup_id2> <file2> <sub_dir2> ...

Obviously, the messages #NOTFOUND <file> or #ERROR <file> can be issued.

The dismount function enables the backup utility to release the resources from the mount. The format of the input file is as follows:

<backup_id1> <file1> <sub_dir1> <backup_id2> <file2> <sub_dir2> …

The format of the output file is:

#DISMOUNTED <backup_id1> <file1> <sub_dir1> #DISMOUNTED <backup_id2> <file2> <sub_dir2> ...

Here too, the messages #NOTFOUND <file> or #ERROR <file> can be issued.

New BACKINT Option –n (negative)

With the new option –n, BACKINT can receive a negative list of files that are on the backup volumes but are not processed and do not appear in reports. This optional option has the following syntax:

where <nlist_file> is a text file containing a list of non-database files or directories in the following format (one file name per line):

<nfile_name1> <nfile_name2> …

The files in the list are normally non-database files that are located on the database disk volumes, but are not explicitly specified in the input file, and are therefore not part of the backup/restore action. They can be implicitly processed but are never reported in the BACKINT interface messages #SAVED, #RESTORED, #BACKUP, #MOUNTED, #DISMOUNTED, #NOTFOUND, #ERROR, and #ERRFILE. Especially during a restore, they might be overwritten without prior warning. If a directory name is given, this is valid recursively for all files and sub-directories in the given directory.

For each entry in the negative list, the overlying directories are implicitly part of the negative list, but not their content. Unlike directories mentioned in the negative list, these directories are not recursively processed.

If $SAPDATA_HOME/sapdata1/a/b/c is in the negative list, this means that:

o $SAPDATA_HOME/sapdata1/a/b and $SAPDATA_HOME/sapdata1/a are also implicitly in the negative list.

o $SAPDATA_HOME/sapdata1/a/b/d or $SAPDATA_HOME/sapdata1/a/e are not in the negative list.

It does not matter whether $SAPDATA_HOME/sapdata1/a/b/c is a file, a directory, or does not even exist.

The value no_check deactivates the completeness check of the files in the input list. See “New Values volume and volume_online for BACKINT Option -t (type)” [page 22]. If this is set, all files located on the backup volumes but not in the input list can be implicitly processed. In this case no message is issued such as #SAVED, #RESTORED, #BACKUP, #MOUNTED, #DISMOUNTED, #NOTFOUND, #ERROR, or #ERRFILE. There is also no warning when these files are to be overwritten by the restore.

The user can specify files that are in the negative list in a new BR*Tools parameter util_vol_nlist. For more information, see “util_vol_nlist = (<nfile_name1>, <nfile_name2>, …) | no_check” [page 28].

Extended Output of Information on the Backup Utility Volume

The following existing message optionally contains the backup volume name: #SAVED <backup_id> <file> [<backup_vol>]

This is being extended to the #RESTORED message of the restore and the #BACKUP message of the inquire functions as follows, where <backup_vol> can contain up to 10 characters (one word):

#RESTORED <backup_id> <file> [<backup_vol>] #BACKUP <backup_id> <file> [<backup_vol>] #BACKUP <backup_id> [<backup_vol>]

We recommend you to generate the name of <backup_vol> so that the user can easily recognize the type of backup involved (for example, tape label, snapshot ID, clone ID). Therefore, we can describe this as generalized information on the backup volume. Therefore, in backup configurations where different types of backup are being created, we strongly recommend you to output volume information, although this is actually optional.

User-Defined Additional Options for BACKINT

With the BR*Tools parameters util_vol_options and util_options you can define any additional options for the BACKINT call. See below: util_vol_options = “< backint_volume_backup_options>” [Page 29] and “util_options = < backint_options>” [page 29]. If these have been defined, BR*Tools puts them in the BACKINT command line after the standard options.

For example, assume that the parameter util_vol_options is set: util_vol_options = "-server backserv1 -clone"

This changes the BACKINT standard call as follows:

Before:

backint.exe -u NT1 -f backup -i D:\oracle\NT1\sapbackup\.bdvcyuxd.lst -t file_online -p initNT1.utl -c

After:

backint.exe -u NT1 -f backup -i D:\oracle\NT1\sapbackup\.bdvcyuxd.lst -t file_online -p initNT1.utl -c -server backserv1 -clone

This new functionality enables you to pass call-specific control information to the BACKINT program. Make sure that the command syntax remains valid and that the additional options do not conflict with the standard options.

To avoid conflicts with possible future extensions to the BACKINT interface, we recommend using complete keywords or capital letters for option names in the util_vol_options and util_options parameters.

Optional Progress Information Generated by BACKINT

BACKINT can now send information about the progress of the executing action to BR*Tools, using the following message:

#DONE <percentage>

where <percentage> is the percentage of work completed in the format nnn.dd (that is, to 2 decimal places), in the range 0.01 to 100.00. For example:

#DONE 30.12

For reasons of clarity, we recommend that you send the progress information messages according to the following percentages:

1, 2, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 100

For example, when progress exceeds 40% – for example, it reaches 41.30% – you can issue a message that the job is 41.30% complete. Then you wait until progress exceeds the next threshold – 45% in this example – before issuing the next progress message.

These progress information messages are only necessary for long-running actions, not for short actions such as “mount”, “dismount”, “inquire” and also backup/restore using a snapshot or clone.

Optional Database Suspend and Resume for Disk Split

If technically necessary, BACKINT can suspend the database for a disk split during an online backup. This is achieved by sending a message #SUSPEND DATABASE to BRBACKUP. The database resumes I/O after the #RESUME DATABASE message has been received.

The logic used for this corresponds to the well-known hand-shaking logic in the functions file_online and volume_online and looks as follows:

1. BACKINT puts all files with the #BEGIN message in backup mode. All files to be backed up should be written to a single .switch.lis file.

2. BACKINT waits for confirmation from BRBACKUP via the .switch.sem and .switch.log files. 3. BACKINT sends a #SUSPEND DATABASE message in the .switch.lst file to BRBACKUP.

4. BRBACKUP (in fact, BRCONNECT) suspends the database with the SQL command ALTER SYSTEM SUSPEND.

5. BACKINT waits for confirmation from BRBACKUP via the .switch.sem and .switch.log files. 6. BACKINT splits the disks and creates a clone or snapshot.

7. BACKINT sends a #RESUME DATABASE message in the .switch.lst file to BRBACKUP.

8. BRBACKUP (in fact, BRCONNECT) activates database I/O with the SQL command ALTER SYSTEM RESUME.

9. BACKINT waits for confirmation from BRBACKUP via the .switch.sem and .switch.log files. 10. BACKINT takes all files with the #END message out of backup mode.

All files to be backed up should be written to a single .switch.lis file.

11. BACKINT waits for confirmation from BRBACKUP via the .switch.sem and the .switch.log files. 12. Optionally, BACKINT backs up all files from the clone or snapshot to a tertiary medium, if the clone or

snapshot alone is insufficient as backup.

13. BACKINT reports all successfully backed up files with the #SAVED message to BRBACKUP.

Only use the above produce when it is absolutely necessary to suspend database I/O for the split. The database suspend phase should be no longer than a few seconds, since all applications are stopped during this phase and all users must wait.

URL for Additional Backup/Restore Information

BACKINT now has the option to return a URL to BR*Tools. The URL lets the user display additional information about the executed backup/restore actions. This URL leads directly to the browse pages generated by the backup tool. The URL is passed to BR*Tools with the following message:

#BIURL <descriptor> URL: <url> where:

<descriptor> is the name of the link <url> is the target URL address of the link

This link is activated in the GUI of BR*Tools (BRGUI or BR*Tools Studio).

Additional Environment Variables for BACKINT

The following additional environment variables for BR*Tools are set before the BACKINT call:

 BI_RUN = <run_id>

This is a unique ID from a BR*Tools run (normally it is the name of the BR*Tools log). If BACKINT programs are called multiple times in a run of BR*Tools, the variable remains the same. (If this variable is set then you can be sure that the call comes from BR*Tools 7.10 or higher).

 BI_CALL = FIRST | NEXT | LAST

This variable specifies whether, in a BR*Tools run, the BACKINT call is first, last, or inbetween. The value LAST is only set by BRARCHIVE and BRBACKUP. In the event of a hard crash, this might also not occur here.

 BI_TYPE = ONLINE|OFFLINE

This variable specifies the database backup type (online or offline). Only BRBACKUP sets this variable.

This variable specifies the database backup mode. Only BRBACKUP sets this variable. o ALL whole database backup: backup_mode = all

o FULL full database backup: level 0 incremental, backup_mode = full o INCR incremental database backup: level 1 incremental, backup_mode = incr,

not for volume backup o NONDB non-database backup:

backup_mode = <non_db_file_list>|<non_db_dir_list>, not for volume backup

o PARTIAL partial database backup:

backup_mode = <db_tsp_list>|< db_file_list>, normally not for volume backup

 In addition, environment variables are set for SAPARCH, SAPBACKUP, SAPCHECK, SAPREORG, and SAPTRACE, which point to the relevant log directory of BR*Tools or Oracle.

New BR*Tools Parameters for Volume Backup in the init<DBSID>.sap

Profile

backup_dev_type = util_vol | util_vol_online

These are two new parameter values for the standard BR*Tools parameter that define the backup device type:

 util_vol

Defines a backup at disk-volume level, resulting in a BACKINT call with –t volume.

 util_vol_online

Defines a backup at disk-volume level with dynamic switching of tablespace backup status, resulting in a BACKINT call with -t volume_online.

Since backups at disk-volume level are not valid for backups of archive log files, BRARCHIVE ignores these values and instead always uses util_file. util_vol_online is only accepted by BRBACKUP.

BRRESTORE accepts only util_vol.

Of course, you can also enter these values directly in the option –d|-device on the command line of BRBACKUP and BRRESTORE. BRRECOVER only uses the inquire function at volume level – for a corresponding restore, BRRESTORE is always called.

util_vol_unit = disk_vol | sap_data | all_data | all_dbf

Default : sap_data

This new parameter defines the smallest unit to be considered as a disk volume in the corresponding configuration (see “Concepts” [page 21]). The possible values are as follows:

 disk_vol – specifies that the smallest unit is a logical volume, file system, raw disk , or disk drive This value is used when a snapshot or clone is created at logical-volume level, and the volumes are mounted on the subdirectories of the sapdata directories, as in the following example:

/oracle/SID/sapdata5/fact_1/fact.data1 is located on a separate file system, which is mounted on: /oracle/SID/sapdata5/fact_1

This is allowed but does not conform to SAP conventions.

This value is used when a snapshot or clone is created at logical-volume or volume-group level, and the volumes are mounted on sapdata, origlog, or mirrlog. This means that the disk configuration is such that all the directories sapdata, origlog, or mirrlog are mount points that can be separately and independently split. If the split is done on volume-group level, only one logical volume can be created for each volume group.

 all_data – specifies that the smallest unit is all sapdata, sapraw, all origlog, or all mirrlog directories

This value is used when many or all sapdata directories are located on logical volumes belonging to the same volume group and the split can only be performed at volume group level. With this configuration, and directories must be on separate volume groups. Therefore, in this category there are at least three volume groups.

 all_dbf – specifies that the smallest unit is all database files

This value is used when all and all and directories are located on a volume group and the volume group as a whole can be split. This means that there is only one split for all database files.

This is allowed but does not conform to SAP conventions because it contradicts the SAP recommendation on the separation of data files and redo log files.

util_vol_access = none | copy | mount | both

Default: none

This new parameter defines the type of access to the files backed up with util_vol, in addition to the obligatory restore of the files on the original location (snap-back, clone-back) mainly for the purpose of a verification. See “New Values volume and volume_online for BACKINT Option -t (type)” [page 22]. The values copy and both also enable a restore to other directories.

none – there are no additional access possibilities on the local computer. In this case such access on another computer is required for verification.

copy – specifies that the backup utility can copy saved files individually to another target directory. This can be a temporary location for verification purposes or a new restore location.

mount – specifies that the saved files can be mounted locally by the backup utility with other paths, where they can be accessed for verification purposes. See “New Values mount and dismount for BACKINT Option -f (-function)” [page 23].

both – specifies that both access types, copy and mount, are possible.

util_vol_nlist = (<nfile_name1>, <nfile_name2>, …) | no_check

This parameter defines a list of non-database files or directories that are located on the database disk volumes but that need not appear in the list of files to back up in the input file. These files can be

automatically included in the backup, but are never reported in the BACKINT interface messages, especially not in the #ERRFILE message. See “New Values volume and volume_online for BACKINT Option -t (type)” [page 22].

During a restore, these files (and possibly fixed files) might be overwritten without prior warning. This check makes sure that the backup volumes do not contain either non-database files or database files belonging to a database other than the one to be backed up. no_check deactivates the BACKINT check of the backup volumes. When no_check is set, the user takes responsibility for making sure that the database volumes (directories sapdata, origlog, and mirrlog) only contain database files of the database to be

backed up. Or, if the database volumes contain either non-database files or database files from a database other than the one to be backed up, the user accepts that such files can be overwritten without warning.

util_vol_options = “< backint_volume_backup_options>”

Default: value of util_options if set.

util_options = < backint_options>

No default.

These new parameters define additional BACKINT options, which BR*Tools places after the standard command-line options when calling the BACKINT program. See “User-Defined Additional Options for BACKINT” [page 25].

util_vol_options is used for volume backup; util_options is used for file backup.

util_vol_path = <backint_volume_backup_directory>

Default: value of util_path if set, otherwise the standard directory for SAP executables

util_path = <backint_directory>

Default: standard directory for SAP executables

These new parameters define the path name to the directory from which BR*Tools calls the BACKINT executable.

util_vol_path is used for volume backup; util_path is used for file backup.

The customer and backup partner are responsible for making sure that the values of these parameters do in fact correspond to the actual configuration of the disk storage and BACKINT functionality.

Copying of Snapshot or Clone Files to Tertiary Storage

With snapshot or cloning technologies it is often possible to copy the snapshot or clone files to tertiary storage such as tape or disk. These copies are then normally available for a longer period of time for restore than the snapshots or clones. These copy procedures are not directly supported by BR*Tools (BACKINT interface). However, they can be performed fully internally by the backup utility.

It is possible to inform BR*Tools of the availability of such copies, so that they can then still be used for restore or verification purposes. A restore or verification from a backup taken at disk-volume level is always performed using a BACKINT call with the option –t volume. A restore or verification of a tertiary copy of a backup taken at disk-volume level is performed using a BACKINT call with the option –t file. The

prerequisite for this is that both actions use the same BACKINT backup IDs.

For example, for a BRRESTORE call with the option –d util_vol, which refers to a BRBACKUP run of the same option, it is expected that for this action the corresponding snapshot or clone is used. In contrast, for a BRRESTORE call with option –d util_file, which refers to a BRBACKUP run with the option –d util_vol, it is expected that for this action the corresponding tertiary copies of the snapshots or clones are used (if available, otherwise it is an error). Obviously the backup utility can (or even should) internally and automatically switch to the corresponding tertiary copies for a BRRESTORE call with option –d util_vol, if the snapshot or clone is no longer available.

BR*Tools can detect whether tertiary copies of snapshots or clones are available using the inquire function. An inquire function with option –t volume delivers and confirms all available disk-volume backups and no others. In contrast, an inquire function with the option –t file delivers and confirms all available individual file backups plus the available tertiary copies of snapshots or clients, whereby for the tertiary copies the same backup IDs are returned for the corresponding original backups at disk-volume level.

BRRECOVER calls the BACKINT inquire function twice with –t file and –t volume to check the availability of all backups.

From the point of view of the BACKINT interface this functionality is optional.

Examples of Backup, Restore/Recovery and Verify Procedures

In the examples below, the BACKINT option –t volume_online is not considered, because the difference between –t volume_online and –t volume corresponds to the difference between –t file_online and –t file.

Complete Online Backup of the Database with Verification on Database Host with

“mount” Access

brbackup -u / -c -t online -m all -d util_vol -w use_dbv util_vol_unit = sap_data

util_vol_access = mount

Verification is performed by the Oracle DBVERIFY utility. The backup runs in the following phases:

 A copy of control file cntrl<SID>.dbf is created in the sapbackup directory.

 BRBACKUP calls BACKINT with –f backup –t volume and a list of all database files in the input file (for an offline backup the list would also contain the online redo log files and a control file)

 Only for verification, BRBACKUP calls BACKINT with –f mount –t volume and a list off all database files in the input file. BACKINT mounts the files from the disk volume backup from the first step and reports the mount subdirectories in the output file.

 Only for verification, BRBACKUP verifies the mounted backup files using the Oracle DBVERIFY utility.

 Only for verification, BRBACKUP calls BACKINT with –f dismount –t volume and a list of all database files with mount subdirectories in the input file. BACKINT dismounts the files and releases the mount resources.

 BRBACKUP calls BACKINT with –f backup –t file and the names of the control file copies in the input file (for a consistent online backup, online_cons, the list would also contain the offline redo log files generated by Oracle during the backup)

 Only for verification, BRBACKUP calls BACKINT with –f restore –t file and the names of the control file copy and the new restore directory <dest_dir> in the input file.

 Only for verification, BRBACKUP verifies the restored control file copy in the restore directory (normally sapreorg).

 BRBACKUP calls BACKINT with –f backup –t file and the names of profiles and log files in the input file.

Complete Offline Backup of the Database with Verification on Database Host with

“copy” Access

brbackup –u / –c –t offline –m all –d util_vol –w use_dbv util_vol_unit = sap_data

util_vol_access = copy

Verification is performed by the Oracle DBVERIFY utility. Since this is an offline backup, no copy of the control file cntrl<SID>.dbf is created in the sapbackup directory.