bc-bri backint interface for oracle databases

Interface Specification:

Oracle Database Administration

BC-BRI BACKINT Interface for Oracle Databases

May 2003

© Copyright 2003 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft®, WINDOWS®, NT®, EXCEL®, Word®, PowerPoint® and SQL Server® are registered trademarks of Microsoft Corporation. IBM®, DB2®, DB2 Universal Database, OS/2®, Parallel Sysplex®, MVS/ESA, AIX®, S/390®, AS/400®, OS/390®, OS/400®, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere®, Netfinity®, Tivoli®, Informix and Informix® Dynamic Server

TM are

trademarks of IBM Corp. in USA and/or other countries. ORACLE® is a registered trademark of ORACLE Corporation. UNIX®, X/Open®, OSF/1®, and Motif ® are registered trademarks of the Open Group. LINUX is a registered trademark of Linus Torvalds and others. Citrix®, the Citrix logo, ICA®, Program Neighborhood ®, MetaFrame®, WinFrame®, VideoFrame®, MultiWin® and other Citrix product names referenced herein are trademarks of Citrix Systems, Inc. HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

JAVA® is a registered trademark of Sun Microsystems, Inc.

J2EE™ is a registered trademark of Sun Microsystems, Inc. JAVASCRIPT® is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. SAP, SAP Logo, R/2, RIVA, R/3, SAP ArchiveLink, SAP Business Workflow, WebFlow, SAP EarlyWatch, BAPI, SAPPHIRE, Management Cockpit, mySAP, mySAP.com, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. MarketSet and Enterprise Buyer are jointly owned trademarks of SAP Markets and Commerce One. All other product and service names mentioned are the trademarks of their respective owners. Disclaimer Some components of this product are based on Java™. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components. Any Java™ Source Code delivered with this product is only to be used by SAP’s Support Services and may not be modified or altered in any way. Documentation in the SAP Service Marketplace You can find this documentation at the following address: http://service.sap.com/dbaora

SAP AG Neurottstraße 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com

Typographic Conventions

Type Style Represents

Example Text Words or characters that appear on the screen. These include field names, screen titles, pushbuttons as well as menu names, paths and options.

Cross-references to other documentation

Example text Emphasized words or phrases in body text, titles of graphics and tables

EXAMPLE TEXT Names of elements in the system. These include report names, program names, transaction codes, table names, and individual key words of a programming language, when surrounded by body text, for example, SELECT and INCLUDE.

Example text Screen output. This includes file and directory names and their paths, messages, names of variables and parameters, source code as well as names of installation, upgrade and database tools.

Example text Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation.

<Example text> Variable user entry. Pointed brackets indicate that you replace these words and characters with appropriate entries.

EXAMPLE TEXT Keys on the keyboard, for example, function keys (such as F2) or the Enter key.

Icons

Icon Meaning

Caution

Example

Note

Recommendation

Syntax


May 2003 4

Contents Introduction to BR*Tools ................................................................................... 5

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

BRBACKUP ........................................................................................................................ 6

BRARCHIVE ....................................................................................................................... 7

BRRESTORE ...................................................................................................................... 7 BACKINT Interface to External Backup Tools .................................................................... 8

BRRECOVER ...................................................................................................................... 8

Link to the Computing Center Management System .......................................................... 9

BACKINT Interface for Oracle Databases ........................................................ 11

Interface Functions .......................................................................................................... 11

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

Basic Parameters ............................................................................................................. 12

Control Parameters .......................................................................................................... 15 BACKINT Return Code ..................................................................................................... 17

Examples.......................................................................................................................... 17

Known Problems and Additional Information .................................................................. 19

Appendix A: Quick Test Environment.............................................................. 22

Installing the Oracle Database ......................................................................................... 22

Creation of Database Objects .......................................................................................... 22

Installation of BR*Tools ................................................................................................... 23

Installation of BACKINT ................................................................................................... 23 Users, Privileges, and Environment ................................................................................. 23

Installation Information .................................................................................................... 24

Testing Information.......................................................................................................... 24

Appendix B: BACKINT Interface Test .............................................................. 26

References ....................................................................................................... 27


May 2003 5

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. Backup programs that meet all requirements for a comprehensive backup are available for the mainframe environment. 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 as described below.

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

�� BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER

Database backup, restore and recovery

�� BRSPACE (as of SAP Web Application Server Release 6.40)

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” below.

The following platforms are supported:

HP-UX, AIX, Solaris, TRU64, Windows, Linux

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 and 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 NT (for a backup to disk: copy, MKS-dd)

�� External backup programs accessed using the BACKINT interface program – see graphic “Backup of the Oracle Database Using an External Backup Tool” [page 8] and the Oracle Recovery Manager (RMAN)

1 MKS and MKS Toolkit are trademarks of Mortice Kern Systems Inc.


May 2003 6

Oracle Backup (Native) Using cpio or dd

Oracle Database

BRARCHIVE

BRRECOVER

BRBACKUPBRRESTORE

Detaillog

Detaillog

Data files Online redo log files

Offline redo log files

Control files

BackupMedia

cpio/ddserial

cpio/ddparallel

BackupMedia

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

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.

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 graphic “Oracle Backup (Native) Using cpio or dd“ [page 6] above. 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 mode (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.


May 2003 7

�� Uses software compression, if this option is set.

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

BRCONNECT makes sure that the database status required for the online or offline backup remains unchanged during the backup.

You can also backup 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 27].

BRBACKUP is not the best tool 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 graphic “Oracle Backup (Native) Using cpio or dd“ [page 6] above. 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.

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

�� Profiles and logs (normally not necessary)

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 mounts sapdata<n> must exist.


May 2003 8

BACKINT Interface to External Backup Tools SAP backup programs can call the BACKINT interface program, enabling them 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

The SAP programs BRBACKUP, BRARCHIVE, and BRRECOVER 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 BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER.

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.

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 and the main log 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


May 2003 9

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 BRRECOVER, BRBACKUP, BRARCHIVE, and BRRESTORE 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 andRecovery

Detail andsummary

log

Detail andsummary

log

BRRESTOREBRBACKUP BRARCHIVE

BRRECOVER

Detail andsummary

log

Data files Online redolog files

Offline redo log filesControl files

Oracle Database

Link to the Computing Center Management System The Computing Center Management System (CCMS) – see “References” [page 27] – supports the use of BRBACKUP 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.

CCMS lets you display the following:

�� An overview of all backups performed using BRBACKUP or BRARCHIVE (see graphic “” below)

�� All details – see graphic “Backup Details in CCMS”[page 7], including the action runtimes and the amount of data transferred


May 2003 10

Backup Overview in CCMS

Backup Details in CCMS


May 2003 11

BACKINT Interface for Oracle Databases The link from the SAP programs – that is, BRBACKUP, BRARCHIVE, and BRRESTORE – to the external backup and restore program is based on the interface program BACKINT. See graphic “Backup of the Oracle Database Using an External Backup Tool” [page 7]. 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 graphic “Backup of the Oracle Database Using an External Backup Tool” on 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 value 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 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 one backup run, although this is normally true. It can also identify the backup of a single file or a group of files.


May 2003 12

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 “Basic Parameters” [page 15] below.

In addition to the command line options, the interface also supports some environment variables set by BRBACKUP or BRARCHIVE 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, or BRRESTORE.

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

BRBACKUP or BRARCHIVE 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 graphic “Backup of the Oracle Database Using an External Backup Tool” [page 8]

backup

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

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

file

-c Unattended mode (no interaction with operator

possible) Attended

mode


May 2003 13

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 (examples are 4 KB for AIX, 64 KB for TRU64).

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 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 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. Because profiles and logs remain in a file system and are backed up automatically, 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: Path in $ORACLE_HOME/ Windows NT: File in %SAPBACKUP%

Switch list sapbackup/.switch.lis .switch.lis

Switch semaphore sapbackup/.switch.sem .switch.sem

Switch log sapbackup/.switch.log .switch.log

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.


May 2003 14

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 all 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) to 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 is deleted by BRBACKUP (actually, BRCONNECT).

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

After the switch semaphore file has been deleted, BACKINT opens and reads the switchlog 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 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 and then issues and logs the appropriate begin/end backup statements. 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.

Only one process can communicate with BRBACKUP (actually, BRCONNECT) in order to perform the tablespace status switch. If you are using multiple parallel 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.


May 2003 15

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), 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 File 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

<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” [page 17].

#NULL

[<backup_id>]

[#NULL <file1>]

[<backup_id> <file2>]

<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.


May 2003 16

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 File Format

Function Successful Completion No Backup or Error 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>

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

BACKINT should avoid writing any 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) <backup_id> Backup ID 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.


May 2003 17

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, or BRRESTORE. 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: OS> backint -u C11 -f backup -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


May 2003 18

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] above.

�� 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


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] above.

�� Inquire

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


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] above.


May 2003 19

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 utility and 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 implemented 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 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.


May 2003 20

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 during the 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.

This extension to BRBACKUP functionality has no effect on the BACKINT specification.


May 2003 21


May 2003 22

Appendix A: Quick Test Environment This section tells you how to create a quick test environment for BRBACKUP, BRARCHIVE, and BRRESTORE together with BACKINT.

Installing the Oracle Database Install a standard Oracle database. You need roughly 300 MB of free space for the database.

You perform the following main steps to install the database:

1. Copy the binaries, scripts, and other utilities.

2. Create the database.

Use the standard directory tree /oracle/C11 for the installation, so that the resulting directories have names like:

�� /oracle/C11/rdbms (admin(scripts), and so on)

�� /oracle/C11/bin (sqlplus, oracle, and so on)

�� /oracle/C11/dbs (initC11.ora, initC11.sap)

�� /oracle/C11/sapbackup (empty directory)

�� /oracle/C11/saparch (empty directory)

�� /oracle/C11/sapreorg (empty directory)

For Windows, SAP distinguishes between the “Oracle software tree” <DRIVE1>:\orant and the “database tree” <DRIVE2>:\oracle\C11.

For Windows you will have something like:

�� <DRIVE1>:\orant\database (admin(scripts), initC11.ora, initC11.sap)

�� <DRIVE1>:\orant\bin (sqlplus, oracle, and so on)

�� <DRIVE2>:\oracle\C11\sapbackup (empty directory)

�� <DRIVE2>:\oracle\C11\saparchi (empty directory)

�� <DRIVE2>:\oracle\C11\sapreorg (empty directory)

To follow SAP’s naming convention as closely as possible, use the DB parameters:

�� SAPDATA_HOME = /oracle/C11 (or for Windows: <DRIVE1>\oracle\C11)

�� ORACLE_HOME = /oracle/C11 (or for Windows: <DRIVE2>\orant)

�� ORACLE_SID = C11

�� MAXDATAFILES = 255

�� MAXLOGFILES = 16

�� DB_NAME = C11

Specify four online redo log files.

Do not forget to run scripts like catalog.sql, catspace.sql and expview.sql to create the necessary dictionary views.

Creation of Database Objects 1. Create tablespaces:


May 2003 23

SQL> CREATE TABLESPACE PSAPSTABD DATAFILE

'/oracle/C11/sapdata1/stabd_1/stabd.data1' SIZE <size>;

SQL> CREATE TABLESPACE PSAPPROTD DATAFILE

'/oracle/C11/sapdata2/protd_1/protd.data1' SIZE <size>;

2. Add tables to this tablespace.

3. Do the same with indexes normally kept separately from tables: SQL> CREATE TABLESPACE PSAPSTABI DATAFILE

'/oracle/C11/sapdata2/stabi_1/stabi.data1' SIZE <size>;

SQL> CREATE TABLESPACE PSAPPROTI DATAFILE

'/oracle/C11/sapdata1/proti_1/proti.data1' SIZE <size>;

4. Create indexes in this tablespace

Follow the SAP naming conventions for the tablespaces and their data files as described in SAP Database Guide: Oracle and as shown in the example above.

For more information on the documentation, see “References” [page 27].

Fill the tables with a few plausible values.

Installation of BR*Tools Copy the executables for BRBACKUP, BRARCHIVE, BRRESTORE, BRRECOVER, BRCONNECT, and BRTOOLS to the following directory: /usr/sap/C11/SYS/exe/run

The parameter file /oracle/C11/dbs/initC11.sap contains all the backup parameters:

�� Set the defaults (backup device, mode, and so on), to use BACKINT. For example, specify the backup device type as util_file:

backup_dev_type = util_file

�� Specify the BACKINT parameter file util_par_file.

For more information, see the documentation SAP Database Guide: Oracle in “References” [page 27].

Installation of BACKINT Copy the BACKINT executable to /usr/sap/C11/SYS/exe/run.

The parameter file /oracle/C11/dbs/initC11.utl contains parameters for BACKINT and the backup server such as node names, passwords (if necessary), expiration period, and so on. Since the profile name is part of the interface description, it has to be known to BRBACKUP, BRARCHIVE, BRRESTORE, and BRRECOVER.

Users, Privileges, and Environment In general, all executables must belong to the user orac11. Its environment ought to be set to: ORACLE_HOME = /oracle/C11 ORACLE_SID = C11 SAPDATA_HOME = /oracle/C11

The environment is different for Windows: ORACLE_HOME = <DRIVE1>\orant ORACLE_SID = C11 SAPDATA_HOME = <DRIVE2>\oracle\C11 SAPBACKUP = <DRIVE2>\oracle\C11\sapbackup


May 2003 24

SAPARCH = <DRIVE2>\oracle\C11\saparch SAPREORG = <DRIVE2>\oracle\C11\sapreorg

Access rights should include full control. If you have changed the standard password for the Oracle user SYSTEM, start BRBACKUP, BRARCHIVE, and BRRECOVER with the option –u system/<password>

Installation Information A complete SAP System is not necessary to implement and test the BACKINT interface. To get started as quickly as possible, you can use BRBACKUP, BRARCHIVE, or BRRESTORE without BRRECOVER. Refer to the examples as described in the BACKINT interface description. You can even perform the test with a sample Oracle database without meeting SAP-specific requirements such as special tablespace names and so on.

You only need to create empty directories as follows: <SAPDATA_HOME>\sapbackup <SAPDATA_HOME>\saparch <SAPDATA_HOME>\sapreorg

Then copy the executables BRBACKUP, BRARCHIVE, and BRRESTORE to a location where they can be accessed by a user with the proper Oracle environment.

You must also create database user SAPR3 and in its schema the tables SDBAH and SDBAD, as shown in the following script: create table sapr3.sdbah (beg varchar2(14) not null, funct varchar2(3) not null, obj varchar2(16) not null, rc varchar2(4) not null, ende varchar2(14) not null, actid varchar2(10) not null) storage (initial 64K next 64K pctincrease 0 minextents 1 maxextents 100); create table sapr3.sdbad (beg varchar2(14) not null, funct varchar2(3) not null, pos varchar2(4) not null, line varchar2(254) not null) storage (initial 1M next 1M pctincrease 0 minextents 1 maxextents 100); create unique index sapr3.sdbah__0 on sapr3.sdbah (beg, funct) storage (initial 16K next 16K pctincrease 0 minextents 1 maxextents 100); create unique index sapr3.sdbad__0 on sapr3.sdbad (beg, funct, pos) storage (initial 96K next 96K pctincrease 0 minextents 1 maxextents 100);

Testing Information As mentioned above, it is useful to test the examples described in the BACKINT interface description. In addition, also try to perform a backup/restore/recovery using BRRECOVER. In general, perform the following:

1. Backup tests for data files:

To perform a complete backup (offline and online), use BRBACKUP with the option -d util_file

Repeat with option -d util_file_online.

2. Backup tests for offline redo logs:

To back up offline redo log files, use BRARCHIVE with the option -s


May 2003 25

3. Inquire tests for backups:

Use BRRESTORE with the –w|-verify option and check the output. This checks the inquire function.

4. Restore tests for data files and offline redo logs:

�� For a complete restore of data files, use BRRESTORE with the option –m full

�� For a complete restore of offline redo log files, use BRRESTORE with the option –a <seq1>-<seq2>

Complete Test Sequence 1. Back up data files.

2. Produce offline redo log files. For example, you can use the following statement with SQLPLUS: ALTER SYSTEM SWITCH LOGFILE

3. Perform a backup of these offline redo log files using the BRARCHIVE option –sd for “save and delete.”

4. Move and rename one or more data files to make them unknown to the database and then perform a complete database recovery in BRRECOVER to check, find backups, and restore and recover the database.

For more information on the certification test, see “Appendix B: BACKINT Interface Test“ [page 26].


May 2003 26

Appendix B: BACKINT Interface Test 1. The test for BACKINT consists of testing the following requests:

�� backup

�� restore

�� inquire

It checks the return code, the output format and the final result of each request and whether the request complies with the specification.

2. Test for the backup request:

a. Back up tablespace(s) online and offline using the BRBACKUP function util_file.

b. Back up tablespace(s) online using the BRBACKUP function util_file_online.

c. Back up offline redo log files using BRARCHIVE

Perform tests a) and b) for normal files and directories as well as raw devices.

3. Test for the restore request:

a. Restore tablespace(s) using BRRESTORE

b. Restore offline redo logs using BRRESTORE

c. Repeat all of the above restore tests using a different location

Perform test a) for files as well as raw devices.

4. Test for the inquire request:

a. Inquire using all four possible input types as described in the specification.

b. Inquire expired backups


May 2003 27

References 1. You can find the documentation listed below in the SAP Service Marketplace at the following

Internet address: service.sap.com/dbaora

2. Choose Media Library and then the relevant category, for example, Backup and Recovery or General.

�� BR*Tools to Back Up the Oracle Database

�� SAP Database Guide: Oracle

�� Computer Center Management System

bc-bri backint interface for oracle databases

Documents