Oracle7 Enterprise Backup Utility Administrator's Guide Go to Product Documentation Library
Library
Go to books for this product
Product
Go to Contents for this book
Contents
Go to Index
Index



Go to previous file in sequence Go to next file in sequence

Command Script Syntax


This appendix describes the command script syntax for Enterprise Backup Utility command scripts.

Topics covered in this appendix are:

Command Syntax Description and Specification

Syntax in this appendix is given in both syntax diagram and BNF notation. BNF notation is located at the end of this appendix.

UNIX Special Tokens ("?" and "@")

The characters "?" and "@" can be used as macros when specifying datafiles. The "?" character represents ORACLE_HOME, while the "@" character represents ORACLE_SID. EBU expands these symbols with the respective values set in the environment at the time of the run. These should not be used for remap specifiers.

NT Special Tokens (%key%)

The %token% syntax can be used as macros when specifying datafiles. The %token% will be substituted by the corresponding value of the key, from either the environment or the registry. These cannot be used with remap specifiers.

Script Layout

In all the syntax descriptions and examples, the specifiers are on separate lines. This is not a requirement but has been done for clarity. The Enterprise Backup Utility also supports scripts like the following:

backup online db_name = PROD  control_file pfile tablespace = A,B 
log = /opt1/oracle/obackup/log/onln_prodb.log  

Case Sensitivity

The EBU specifiers are case insensitive, but the values specified are case sensitive. Depending on the Operating System, the datafile names will be case-sensitive or not.

The Oracle database is case-sensitive when storing data; however, Oracle7 stores names of tablespaces in uppercase by default, so EBU will peform case-insensitive comparisons when looking at the tablespace list in the script, however, Oracle recommends always using quotes with tablespace names, specifically for use with multibyte character set tablespace names.

Comments

Comments are delimited by "#"and the newline character. When the Enterprise Backup Utility encounters the "#" character on a line, it ignores all remaining characters on that line, and resumes parsing on the next line. Use this capability to annotate your command scripts.

With the Enterprise Backup Utility, comments can also be used as escape sequences for your third-party media management software.

Quotation Marks

In Enterprise Backup Utility Release 2.2 double quotes are not needed for value specifiers unless there are embedded spaces in the value, the value corresponds to one of the EBU reserved words, or the value contains multibyte characters.

For example:

datafile=/oracle/data/mydata.dbf does not need quotes,

while

datafile="/oracle/data/my data.dbf" does require quotes as there is a space in the middle

log="log" requires quotes as log is a keyword

log=output.log does not require quotes

Single quotes should not be used, they are not recognized and will generate syntax errors.

Backup

Purpose

To perform backups of target databases. You can perform the following types of backups:

Prerequisites

For online backups, ensure that the target database is online and you can connect as the backup user to the target database. For offline backups, ensure that the target database is shut down cleanly. For offline backups, the database will be started to verify its configuration in the EBU catalog before the backup, and will again be started after the backup to verify that the database was not opened during the offline backup.

Syntax

Figure A-1 Backup SyntaxBackup Arguments Syntax

Keywords and Parameters
Table A-1 Backup Parameters
Name   Description  

online

 

Specifies that the backup of the target database be taken when the database is open and available for use. Some tablespaces in the database may be offline, but the backup is still considered online. Autoregistration and archived log file backup are enabled by default for online backups. Use -noauto command line option to disable configuration checking.

If database has not been registered before the backup will do the registration, the default OS dependent value will be assigned to pfile.

 

database

 

Specifies all online datafiles, control files, and parameter files be backed up. You cannot use the database specifier in the same command script as the control_file, tablespace, pfile, or dbfile specifiers.

 

tablespace

 

Specifies the list of tablespaces to be backed up. If specified without arguments, all tablespaces in the target database are backed up. To back up only specific tablespaces, enter a list of tablespaces separated by commas. If you use the tablespace specifier, you need not use the dbfile specifier unless you want to backup database files which do not belong to the tablespaces you specify.

 

dbfile

 

Specifies one or more online datafiles in the target database for backup. During a restore, Backup File Sets containing multiplexed files are automatically demultiplexed correctly. You can remap datafiles being restored to a different location with the remap and remap_path specifiers, as long as EBU has write permission on the new destination. If you use the restore to a different location, rename the datafiles before you bring the database back online or use the RENAME specifier so that EBU does this automatically.

Additional Information: For information on renaming files, see the Oracle7 Server Administrators Guide.

 

pfile

 

Specifies that parameter files used by the target database be backed up or restored. If you rename parameter files, use the STARTUP_PFILE to direct EBU to use the newly restored paratmer file for recovery, or if doing recover manually use the pfile option of the startup command when starting up the database. During restore, the Enterprise Backup Utility renames any parameter files existing before they are restored the disk. Parameter files are never overwritten. You cannot specify which parameter files are restored. EBU uses the list of parameter files that were registered with the database.

 

control_file

 

Specifies that the control file(s) of the target database be backed up or restored.

Note: You cannot use the control_file specifier to specify a list of control files. Its usage during backup is not needed unless only the parameter files (and no archivelogs are being backed up), or just the control file wants to be backed up. By default any backup involving datafiles or archivelog files will backup up the control file automatically.

During RESTORE DATABASE or RESTORE DATABASE CONSISTENT , it can be used to direct EBU to overwrite the existing control file(s). A copy of the control file(s) is made before being overwritten by the restore. It can also be used to direct EBU to overwrite the control files in other RESTORE <subset> scenarios.

The database must be shutdown in order for the control file to be restored to its original location.

 

offline database

 

Specifies that the database is shut down and not available for general use during backup. Note that the keywords online and offline are mutually exclusive. The Enterprise Backup Utility does not perform autoregistration for offline backups, although it verifies that the configuration is up to date and refuses to perform the backup if it is not up to date. Use the -noauto option to disable configuration checking for offline backups. Offline datafiles are not backed up by default even in offline backups.

 

startup_pfile

 

Direct EBU to use an altenate parameter file to startup the database to verify its state when performing offline backups. By default EBU will use the default OS dependent default pfile value.

 

db_name

 

Identifies the name of the target database. This specifier is optional; you can include it in each command script. If specified, the database name of the target database should match the specified name, otherwise an error is signaled. If not specified, it is assumed no validation is performed.

 

mux

 

Specifies a list of datafiles that are to be multiplexed into a single BFS. The mux specifier can be used multiple times in a command script. Construct groups of files to be multiplexed together by enclosing the list in parenthesis.

Note: When using the mux specifier, make sure you either specify the database parameter or explicitly specify the tablespace(s) to which the multiplexed datafiles belong in the backup command.

Additional Information: "Multiplexing"".

 

<param_clause>

 

Specifies the pathname to the Enterprise Backup Utility system parameters file. This specifier is optional. You can also specify individual parameters in the command script itself. See "<COMMON_ARGS>".

 

archivelog [ = <arch log directory list> | none]

 

Used to specify whether or not archivelogs are to be backed up, and the list of directories where they are located. The default source directory is the current LOG_ARCHIVE_DEST (obtained by querying the target database). Other destinations can be specified, but these override, not augment, the default. The none specifier indicates that archived logs are not to be backed up.

 

archdelete

 

Specifies that backed up archived log files be deleted. Not enabled by default. The utility will not delete any archived log file it has not backed up.

 

catalog [=none]

 

Used to specify whether or not the EBU catalog is to be backed up.

 

arch_per_bfs

 

Specifies the number of archived redo logs to be placed in each BFS.

 

arch_copies

 

Specifies the number of times to backup the archivelogs in different BFSs to provide archivelog redundancy in case of media failure.

 

allow_corrupt

 

Specifies that files with corrupted RBA block headers are to be patched and backed up in the job. The deafult behavior of EBU will error out if a file with a corrupted RBA header is encountered.

 

include_dbfile

 

Specifies the list of OFFLINE datafiles to be included in the backup. Offline datafiles will be backed up in image mode without block header verification.

 

Examples

Example A-1 backup offline database

backup offline database 
db_name = PROD 
parallel = 4
log = /opt1/oracle/obackup/log/obkPROD.log



Example A-2 backup online database with archivelog backup

backup online archivelog parallel = 3 log = /opt1/oracle/obackup/log/obkPROD.log

Example A-3 backup online tablespace subset with datafile multiplexing and multiple archivelog directories

backup online db_name = "PROD" control_file tablespace = A, B mux = (home/oracle/dbs/A1.dbf, "home/oracle/dbs/B1.dbf","home/oracle/dbs/A2.dbf", home/oracle/dbs/B2.dbf) parallel = 5 archivelog = /home/oracle/archive01, "/home/oracle/archive02"

Example A-4 online backup <subset> with catalog backup disabled

backup online db_name = PROD control_file arch_copies=2 arch_per_bfs=64 tablespace = a, b parallel = 16 log = /opt1/oracle/obackup/log/obkPROD.log param = /opt1/oracle/obackup/defaults.obk catalog = none

Example A-5 offline backup with archdelete specified, non default startup parameter file and offline datafiles

backup offline database archdelete include_dbfile="/opt1/oracle/data/offline1.dbf",/opt1/oracle/data/offline2.dat parallel = 16 startup_pfile=/opt1/oracle/admin/initoffPROD.ora log = /opt1/oracle/obackup/log/obkPROD.log param = "/opt1/oracle/obackup/defaults.obk"

Example A-6 backup online tablespace subset

backup online tablespace = "A","B" parallel = 16 log = "/opt1/oracle/obackup/log/obkPROD.log"

Backup Catalog

Purpose

The backup catalog command creates a logical backup of the EBU catalog.

Prerequisites

The backup catalog database must be started and open. No new EBU jobs can be performed while the EBU catalog is being backed up.

Syntax

Keywords and Parameters

Table A-2 Backup Catalog - Keywords and Specifiers
Keywords   Description  

backup catalog

 

Backs up the EBU catalog.

 

(see backup command)

 

(see backup command keywords and specifiers)

 

Examples

Example A-7 backup catalog

backup catalog


Example A-8 backup catalog using a temporary directory

backup catalog tempdir=c:/temp

Register

Purpose

To register target database information in the EBU Catalog database. This command can be used to register a new target database in the EBU Catalog or to update information for an existing target database.

Prerequisites

The target database must be online to register or update. If the target database is offline, the Enterprise Backup Utility aborts and displays an error message. Check that the catalog.ebu file is in EBU_HOME/admin directory and has the connect string to the backup catalog database. The backup user must have been created in the target database prior to registering the database in the backup catalog. See "Authorizing Target Database Backups".

Syntax

Figure A-2 Register Syntax

Keywords and Parameters
Table A-3 Register Parameters
Name   Description  

db_name

 

Identifies the name of target database. This specifier is optional; you can include it in each command script. If specified the database name of the target database should match the specified name, otherwise an error is signaled. If not specified its assumed no validation is performed.

 

pfile

 

Specifies list of parameter files used by target database. If this keyword is not specified the default OS dependent value is used as the only parameter file.

 

log & trace

 

(See backup command keywords and specifiers for description of log and trace)

 

Examples

Example A-9 register target database with all defaults

register


Example A-10 register to update the List of Parameter Files Associated with the Database

register db_name = "PROD" pfile = ?/dbs/init@.ora,"?/dbs/include@.ora" , ?/dbs/config@.ora"

Additional Information:

For more information on the register command, see Chapter 2.

 

Restore

Purpose

To restore a database in case of media failure, with the option to recover it, as well. This command can be used to perform the following restores:

Prerequisites

Verify that the target database or the specified objects being restored are offline.

Syntax

Figure A-3 Restore Syntax





Keywords and Parameters
Table A-4 Restore Parameters
Name   Description  

database

[consistent]

[controlfile]

 

Specifies that the entire database be restored. If you use the database specifier with the consistent switch, EBU restores only from the most recent backup offline database. Using database consistent to restore your entire database from one backup job means you need not apply redo log files to make the database consistent. Using controlfile indicates that the database controlfile should be restored to the location where it was backed up, overwriting current controlfile.

 

[tablespace|dbfile|pfile|

controlfile]

 

Substitution variable for the restore command. It implies that the Enterprise Backup Utility restores only a part of the database. Explicitly specify the objects to restore in the restore script. Note that database and <subset> are mutually exclusive, except for the CONTROL_FILE specifier, which can be used to indicate to EBU that the control file should be restored replacing the current control files. For more information refer to the "Restore Subset"

 

bfs=<bfsname>,...

 

Restores the listed backup file sets(s).

 

archivelog [ = <arch log dirlist> | none]

 

Used to specify whether or not archivelogs should be restore, and if so so, where they should be restored to.

 

|start_lsn=<thread>:<seq> |end_lsn=<thread>:<seq>

 

Specifiy the thread and logical sequence number range of archved logs to be restored.

 

db_name

 

Identifies the name of target database. This specifier is optional; you can include it in each command script. If specified, the database name of the target database should match the specified name,. Otherwise an error is signaled. If not specified, it is assumed that no validation is performed.

 

to

 

Specifies the point in time to which the Enterprise Backup Utility restores the database.

If this keyword is not used, the utility finds the most recent backup(s) to use in performing the restore. Use the following valid date formats to specify the to parameter:

MM/DD/YYYY (HH24:MI:SS default to 23:59:59)

MM/DD/YYYY HH24 (MI:SS default to 00:00)

MM/DD/YYYY HH24:MI (SS default to 00)

MM/DD/YYYY HH24:MI:SS

 

remap

 

Specifies that files be restored to a new location. See"Remap" for information about remapping.

 

remap_path

 

Specifies that EBU will remap all the files matching the old_file_path file to be restored to the new_file_path See chapter 5 for discussion about remapping.

 

rename

 

Specifies that EBU will rename the datafiles in the database automatically after remapping. This is used in conjunction with the remap or remap_path specifier. This needs to be specified in addition to the remap/remap_path specifier if EBU will be performing automatic recovery.

 

backup_host

 

Specifies the full name of the original backup host when restoring to a different host. You need this specifier to identify the backup set in the EBU Catalog to restore to a new host.

 

recover

[ = [ <scn> | <time> ]

 

Recovers the database following a successful restore. Default is to recover the database to the most recent point in time possible, though earlier points can be specified by either timestamp or SCN.

 

include_dbfile

 

Specifies the list of OFFLINE datafiles to be included in the restore. Files that were offline when backed up are not restored by default. Offline datafiles restored in this way will not be recovered by the automatic recovery option.

 

Example A-11 restore database to point-in-time

restore database
to = "01/01/1994 12:00 


Example A-12 restore database consistent

restore database consistent db_name = "PROD" parallel = 4 log = /opt1/oracle/obackup/log/obkPROD.log"

Example A-13 restore of two tablespaces and control file, with database-wide recovery

restore db_name = prod parallel = 4 control_file tablespace = a, B recover log = "/opt1/oracle/obackup/log/obkPROD.log"

Example A-14 restore tablespace subset

restore db_name = PROD parallel = 4 control_file tablespace = a, B log = "/opt1/oracle/obackup/log/obk@.log"

Example A-15 restore tablespace subset and archivelogs

restore db_name = "PROD" tablespace = A, b archivelog = "/home/oracle/archive03" parallel = 4 control_file log = "/opt1/oracle/obackup/log/obk@.log"

Example A-16 restore database consistent with archivelog range

restore database consistent start_lsn=2:100 end_lsn=2:150 parallel=2 log="c:/orant/obackup/log/racPROD.log"

Example A-17 restore database consistent replacing current control files with the ones in the backup

restore database consistent controlfile parallel = 4 archivelog start_lsn = 65

Restore Catalog

Purpose

To restore the EBU catalog in the event it has been corrupted or the catalog database has been lost. Backups of the EBU catalog are created using by default any time a BACKUP operation is performed or can be created with the BACKUP CATALOG command.

Prerequisites

The backup catalog database must be started and open. No other backup or restore job can be performed while the catalog is being restored.

If restoring the catalog to a new database, the EBU_HOME/admin/catalog.ebu file must be updated to point to the new catalog database before invoking the restore catalog command.

Syntax

Figure A-4 Restore Catalog Syntax

Keywords and Parameters

Table A-5
Keywords   Description  

<cat_db_name>

 

This is the DB_NAME of the backup catalog and must be specified in any restore catalog command. EBU compares this DB_NAME with the DB_NAME of the database specified in EBU_HOME/admin/catalog.ebu. If the two names are not identical, the utility aborts without performing any operations.

 

as

 

When the DB_NAME of the new catalog being restored does not match the DB_NAME of the catalog being restored, this specifier can be used to specify the new database names in which to restore the backup catalog.

Note: The connect information to the new catalog database must be entered in the catalog.ebu file on the EBU_HOME/admin directory from which you are running the restore catalog command, before running the command.

 

to

 

Specifies a date to which the catalog should be restored. EBU restores the most current catalog backup available for the given date.

The valid date format for catalog restore is "MM/DD/YYYY". The time portion of the date format, if specified, is ignored. If no catalog backup can be located within seven days of the specified date, the job fails.

 

seq

 

Specifies the sequence number of the desired catalog backup for the given date. This specifier can only be used if the to specifier has been used before. The sequence number is generated during catalog backup and can be obtained from the log file of the backup job. By specifying the sequence, EBU can be directed to use a specific backup made during the day (and thus achieving full point-in-time restore).

The sequence number indicates the order of catalog backups for any given day, if that sequence is not found, the search continues looking for previous backups for the last 7 days.

 
Restore Catalog - Keywords and Specifiers


Warning:

Oracle Corporation strongly recommends that you restore the catalog to a different location, if you are restoring it to a previous point-in-time.


Examples

Example A-18 restore catalog

restore catalog = EBUCAT
to "12/07/1996"
seq = 9


Example A-19 restore catalog to a new database

restore catalog = EBUCAT as = NEWCAT

<COMMON_ARGS>

Purpose

To specify common parameters for backup, restore, backup catalog, and restore catalog commands.

Syntax

Figure A-5 <COMMON_ARGS> Syntax

Keywords and Parameters
Table A-6 <COMMON_ARGS> - Keywords and Parameters
Keyword   Description  

log

 

Specifies pathname of the Enterprise Backup Utility message log file. This file stores utility runtime messages. The log file can be specified as either a relative or absolute pathname. If unspecified, messages are sent to standard error. Unless the -silent option is used, the output is always send to standard error, besides being send to the log file.

Note: The log file is not a value stored in the backup catalog. Entering log without a corresponding file results in an error.

 

trace

 

Specifies pathname of the Enterprise Backup Utility status trace file. This file stores utility runtime messages. The trace file can be specified as either a relative or absolute pathname. If unspecified, no trace output is generated. Do not use trace unless diagnosing a problem.

Note: Oracle Corporation recommends you specify $EBU_HOME/log as the destination for the log and trace files.

 

parallel

 

Specifies the number of concurrent data streams in reading from or writing to a media device. Specify a value equal to the number of backup devices available. If you do not enter a value, the number of parallel streams defaults to one. Cannot be used with BACKUP/RESTORE CATALOG.

 

param

 

Specifies the pathname to the Enterprise Backup Utility system parameters file. This specifier is optional. You can also specify individual parameters in the command script. Cannot be used with BACKUP/RESTORE CATALOG.

 

test

 

Specifies that you want only a test run. When you use this specifier in a command script, the utility performs the command, except for any destructive operations to tape or disk (such as write operations, for example). This allows you to check the effectiveness of your command scripts before you carry out the specified operation. Cannot be used with checksum specifier or command option.

 

tempdir

 

Directs EBU where to place the restored copies of the logical/physical device controlfile, catalog restore temporary file, and restored pfiles, create the temporary file for the backup of the catalog in the specified directory as it is read from the media(if not spec
ified, the temporary file is created under $EBU_HOME/admin). Default is OS dependent.

 

checksum

 

Performs a checksum on each file being restored and compares it to the information stored in the backup catalog. Cannot be used with test specifier or BACKUP/RESTORE CATALOG.

 

use_io_model=<SHM|AIO>

 

For those platforms that support both I/O models, specify the I/O model to use as described in Chapter 6. Valid values are SHM for Shared Memory and AIO for Asynchronous I/O.

 

<param_clause>

Purpose

To specify tape and disk I/O parameters for backup, restore, backup catalog, and restore catalog commands. Parameters detailed below can either be used as command specifiers or placed in a separate EBU parameter file.

Syntax

Figure A-6 <param_clause> Syntax

Keywords and Parameters
Table A-7 <param_clause> - Keywords and Parameters
Keyword   Description  

param

 

Specifies the name of a file containing settings for the parameters listed below.

 

disk_io_size

 

Size in blocks for each disk I/O request.

 

tape_io_size

 

Size in blocks for each tape I/O request.

 

buffer_size

 

Size of memory buffer for I/O tranfers.

 

tape_retry_count

 

Number of times to re-attempt tape I/O before an error is reported.

 

tape_retry_period

 

Amount of time to wait (seconds) before retrying a failed tape I/O.

 

BNF Notation

BACKUP

BACKUP
{ ONLINE{ DATABASE|
    [TABLESPACE [= "tablespace_name"  [, "tablespace_name"]...]] 
    [DBFILE = "datafile_pathname" [, "datafile_pathname"]...] 
    [PFILE] 
    [CONTROL_FILE] }
}
| OFFLINE DATABASE  [STARTUP_PFILE=pfile_pathname]}
[DB_NAME = "database_name"  ]
[INCLUDE_DBFILE="datafile_pathname" [, "datafile pathname"] 
[MUX =("datafile_pathname" [, "datafile_pathname"]...) 
             [,("datafile_pathname" [, "datafile_pathname"]...)]...]  
[ALLOW_CORRUPT]
[ARCHIVELOG=["archivelog_directory_name"[,"archivelog_directory_name"]...]|
    [NONE]]
[ARCH_PER_BFS = number of archivelogs per bfs]
[ARCH_COPIES = number of copies of achivelog BFSs]
[ARCHDELETE]
[CATALOG [=NONE] ]
[<COMMON_ARGS>]  

BACKUP CATALOG

BACKUP CATALOG
[<COMMON_ARGS>]  

REGISTER

REGISTER 
[DB_NAME = "database_name" ]
[PFILE = "pfile_pathname"  [,"pfile_pathname"...] ]
[LOG[= "message_log_file_pathname"]] 
[TRACE[= "status_trace_file_pathname"]]      

RESTORE

{DATABASE [CONSISTENT] [CONTROL_FILE] | 
    [TABLESPACE [= "tablespace_name"  [, "tablespace_name"]...]] 
    [DBFILE = "datafile_pathname" [, "datafile_pathname"]...] 
    [PFILE] 
    [CONTROL_FILE] 
    [BFS = bfsname [, bfsname]  ] }
[DB_NAME ="database_name" ]
[INCLUDE_DBFILE="datafile_pathname" [, "datafile pathname"]
[TO = MM/DD/YYYY [  HH24 [:MI [:SS] ] ] ]  
[BACKUP_HOST = "full_name_of _original_backup_host"] 
[RECOVER [={SCN | MM/DD/YYYY [  HH24 [:MI [:SS] ] ] } ]
[RENAME]
[REMAP = "old_pathname" to "new_pathname" [,"old_pathname" to 
"new_pathname"]....]  
[REMAP_PATH = "old_pathname" to "new_pathname" [,"old_pathname" to 
"new_pathname"]....]  
[ [ARCHIVELOG=["archivelog_directory_name"] | [NONE]]
  [START_LSN = [THREAD#:] LSN]
  [END_LSN = [THREAD#:] LSN] ]
[<COMMON_ARGS>]  

RESTORE CATALOG

RESTORE CATALOG = catalog_db_name
[AS = new_catalog_db_name ]
[TO = MM/DD/YYYY [SEQ = sequence ] ]  
[<COMMON_ARGS>]  

<COMMON_ARGS>

[TEMPDIR = tempdir_pathname]
[USE_IO_MODEL={SHM|AIO}]
[PARALLEL = number_of_parallel_data_streams]  
[<PARAM_CLAUSE>]  
[CHECKSUM]
[TEST] 
[LOG = "message_log_file_pathname"]  
[TRACE = "status_trace_file_pathname"]  

<PARAM_CLAUSE>

{ PARAM = ebu_parameter_file_pathname |
  [ DISK_IO_SIZE = number_of_blocks ]
  [ TAPE_IO_SIZE = number_of_blocks]
  [ BUFFER_SIZE = number_of_blocks]
  [ TAPE_RETRY_COUNT = number_of_retries ]
  [ TAPE_RETRY_PERIOD = number_of_seconds ] }




Go to previous file in sequence Go to next file in sequence
Prev Next
Oracle
Copyright © 1997 Oracle Corporation.
All Rights Reserved.
Go to Product Documentation Library
Library
Go to books for this product
Product
Go to Contents for this book
Contents
Go to Index
Index