IBM Informix Backup and Restore Guide: Informix Product Family Informix
IBM Informix Backup and Restore Guide: Informix Product Family Informix
Informix
Version 11.70
SC27-3542-05
Informix Product Family
Informix
Version 11.70
SC27-3542-05
Note
Before using this information and the product it supports, read the information in “Notices” on page E-1.
Edition
This edition replaces SC27-3542-04.
This document contains proprietary information of IBM. It is provided under a license agreement and is protected
by copyright law. The information contained in this publication does not include any product warranties, and any
statements provided in this manual should not be interpreted as such.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright IBM Corporation 2006, 2014.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
About this publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Types of users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Software dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Assumptions about your locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Demonstration databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
What's New in the Backup and Restore Guide, Version 11.70 . . . . . . . . . . . . . . . . . . . x
Example code conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Additional documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Compliance with industry standards . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Syntax diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
How to read a command-line syntax diagram . . . . . . . . . . . . . . . . . . . . . . xiv
Keywords and punctuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Identifiers and names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
How to provide documentation feedback . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Contents v
Start an automatic logical-log backup . . . . . . . . . . . . . . . . . . . . . . . . . 12-14
Starting a continuous logical-log file backup . . . . . . . . . . . . . . . . . . . . . . 12-14
End a continuous logical-log backup . . . . . . . . . . . . . . . . . . . . . . . . . 12-15
Devices that logical-log backups must use . . . . . . . . . . . . . . . . . . . . . . . 12-16
Contents vii
Part 6. Appendixes
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1
Privacy policy considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
These utilities enable you to recover your databases after data is lost or becomes
corrupt due to hardware or software failure or accident.
Types of users
These topics were written for the following users:
v Database administrators
v System administrators
v Backup operators
v Technical support personnel
These topics are written with the assumption that you have the following
background:
v Some experience with storage managers, which are applications that manage the
storage devices and media that contain backups
v A working knowledge of your computer, your operating system, and the utilities
that your operating system provides
v Some experience working with relational databases or exposure to database
concepts
v Some experience with database server administration, operating-system
administration, or network administration
You can access the Informix information centers, as well as other technical
information such as technotes, white papers, and IBMRedbooks® publications
online at http://www.ibm.com/software/data/sw-library/.
Software dependencies
This publication is written with the assumption that you are using IBM Informix
Version 11.70 as your database server.
The IBM Informix OLE DB Provider follows the ISO string formats for date, time,
and money, as defined by the Microsoft OLE DB standards. You can override that
default by setting an Informix environment variable or registry entry, such as
DBDATE.
The examples in this publication are written with the assumption that you are
using one of these locales: en_us.8859-1 (ISO 8859-1) on UNIX platforms or
en_us.1252 (Microsoft 1252) in Windows environments. These locales support U.S.
English format conventions for displaying and entering date, time, number, and
currency values. They also support the ISO 8859-1 code set (on UNIX and Linux)
or the Microsoft 1252 code set (on Windows), which includes the ASCII code set
plus many 8-bit characters such as é, è, and ñ.
You can specify another locale if you plan to use characters from other locales in
your data or your SQL identifiers, or if you want to conform to other collation
rules for character data.
For instructions about how to specify locales, additional syntax, and other
considerations related to GLS locales, see the IBM Informix GLS User's Guide.
Demonstration databases
The DB-Access utility, which is provided with your IBM Informix database server
products, includes one or more of the following demonstration databases:
v The stores_demo database illustrates a relational schema with information about
a fictitious wholesale sporting-goods distributor. Many examples in IBM
Informix publications are based on the stores_demo database.
v The superstores_demo database illustrates an object-relational schema. The
superstores_demo database contains examples of extended data types, type and
table inheritance, and user-defined routines.
For information about how to create and populate the demonstration databases,
see the IBM Informix DB-Access User's Guide. For descriptions of the databases and
their contents, see the IBM Informix Guide to SQL: Reference.
The scripts that you use to install the demonstration databases are in the
$INFORMIXDIR/bin directory on UNIX platforms and in the %INFORMIXDIR%\bin
directory in Windows environments.
The following changes and enhancements are relevant to this publication. For a
complete list of what's new in this release, see the release notes or the information
center at http://pic.dhe.ibm.com/infocenter/idshelp/v117/topic/com.ibm.po.doc/
new_features.htm.
Table 2. What's New in IBM Informix Backup and Restore Guide for version 11.70.xC1
Overview Reference
New editions and product names For more information about the Informix product family,
go to http://www.ibm.com/software/data/informix/.
IBM Informix Dynamic Server editions were withdrawn
and new Informix editions are available. Some products
were also renamed. The publications in the Informix
library pertain to the following products:
v IBM Informix database server, formerly known as IBM
Informix Dynamic Server (IDS)
v IBM OpenAdmin Tool (OAT) for Informix, formerly
known as OpenAdmin Tool for Informix Dynamic
Server (IDS)
v IBM Informix SQL Warehousing Tool, formerly known
as Informix Warehouse Feature
Backup and restore is now cloud aware “Back up to Amazon Simple Storage Service” on page
12-9
You can use the ontape utility to back up and restore
Informix database data to or from cloud storage. Storing
data on the cloud provides scalable storage that can be
accessed from the web.
Introduction xi
Table 2. What's New in IBM Informix Backup and Restore Guide for version 11.70.xC1 (continued)
Overview Reference
Preventing a timeout during a backup on a remote “BAR_CKPTSEC_TIMEOUT configuration parameter” on
stand-alone secondary server page 16-5
If only SQL statements are listed in the example, they are not delimited by
semicolons. For instance, you might see the code in the following example:
CONNECT TO stores_demo
...
COMMIT WORK
DISCONNECT CURRENT
To use this SQL code for a specific product, you must apply the syntax rules for
that product. For example, if you are using an SQL API, you must use EXEC SQL
at the start of each statement and a semicolon (or other appropriate delimiter) at
the end of the statement. If you are using DB–Access, you must delimit multiple
statements with semicolons.
Tip: Ellipsis points in a code example indicate that more code would be added in
a full application, but it is not necessary to show it to describe the concept that is
being discussed.
Additional documentation
Documentation about this release of IBM Informix products is available in various
formats.
Syntax diagrams
Syntax diagrams use special components to describe the syntax for statements and
commands.
Table 3. Syntax Diagram Components
Component represented in PDF Component represented in HTML Meaning
Introduction xiii
Table 3. Syntax Diagram Components (continued)
Component represented in PDF Component represented in HTML Meaning
Table Reference Syntax segment.
|--+-----view--------+--|
+------table------+
’----synonym------’
-t table
(1)
Setting the Run Mode
-S server -T target
Notes:
1 See page Z-1
This diagram has a segment that is named “Setting the Run Mode,” which
according to the diagram footnote is on page Z-1. If this was an actual
cross-reference, you would find this segment on the first page of Appendix Z.
Instead, this segment is shown in the following segment diagram. Notice that the
diagram uses segment start and end components.
l
c
-f
d u n N
p
a
To see how to construct a command correctly, start at the upper left of the main
diagram. Follow the diagram to the right, including the elements that you want.
The elements in this diagram are case-sensitive because they illustrate utility
syntax. Other types of syntax, such as SQL, are not case-sensitive.
You must also use any punctuation in your statements and commands exactly as
shown in the syntax diagrams.
You can replace a variable with an arbitrary name, identifier, or literal, depending
on the context. Variables are also used to represent complex syntax elements that
are expanded in other syntax diagrams. A variable in a syntax diagram, an
example, or text, is shown in lowercase italic.
The following syntax diagram uses variables to illustrate the general form of a
simple SELECT statement.
When you write a SELECT statement of this form, you replace the variables
column_name and table_name with the name of a specific column and table.
Introduction xv
How to provide documentation feedback
You are encouraged to send your comments about IBM Informix user
documentation.
Feedback from all methods is monitored by the team that maintains the user
documentation. The feedback methods are reserved for reporting errors and
omissions in the documentation. For immediate help with a technical problem,
contact IBM Technical Support at http://www.ibm.com/planetwide/.
ON-Bar backs up and restores storage spaces (dbspaces) and logical file, by using a
storage manager, whereas ontape does not use a storage manager.
Recovery system
A recovery system, which includes backup and restore systems, enables you to back
up your database server data and later restore it if your current data becomes
corrupted or inaccessible.
The causes of data corruption or loss can range from a program error to a disk
failure to a disaster that damages the entire facility. A recovery system enables you
to recover data that you already lost due to such mishaps.
Backup systems
A backup is a copy of one or more dbspaces (also called storage spaces) and logical
logs that the database server maintains. You can also back up blobspaces and
sbspaces.
The backup copy is typically written to a secondary storage medium such as disk or
magnetic tape. Store the media offline and keep a copy off site if possible.
The backup copy is typically written to a secondary storage medium such as disk,
magnetic tape, or optical disk. Store the media offline and keep a copy off site if
possible.
Backup media
You do not always have to back up all the storage spaces. If some tables change
daily but others rarely change, it is inefficient to back up the storage spaces that
contain the unchanged tables every time that you back up the database server. You
need to plan your backup schedule carefully to avoid long delays for backing up
or restoring data.
Important: If disks and other media are destroyed and need to be replaced, you
need at least a level-0 backup of all storage spaces and relevant logical logs to
restore data completely on the replacement hardware.
Related reference:
“Schedule backups” on page 2-2
Logical-log backup
A logical-log backup is a copy to disk or tape of all full logical-log files. The
logical-log files store a record of database server activity that occurs between
backups.
To free full logical-log files, back them up. The database server reuses the freed
logical-log files for recording new transactions. For a complete description of the
logical log, see your IBM Informix Administrator's Guide.
Restriction: Even if you do not specify logging for databases or tables, you need
to back up the logical logs because they contain administrative information such as
A manual logical-log backup backs up all the full logical-log files and stops at the
current logical-log file. You must monitor your logical logs carefully and start
logical-log backups as needed.
To find out if a logical-log file is ready to be backed up, check the flags field of
onstat -l. After the logical-log file is marked as backed up, it can be reused. When
the flags field displays any of the following values, the logical-log file is ready to
be backed up:
U------
U-----L
The value U means that the logical-log file is used. The value L means that the last
checkpoint occurred when the indicated logical-log file was current. The value C
indicates the current log. If B appears in the third column, the logical-log file is
already backed up and can be reused.
U-B---L
The flag values U---C-L or U---C-- represent the current logical log. While you are
allowed to back up the current logical log, doing so forces a log switch that wastes
logical-log space. Wait until a logical-log file fills before you back it up.
If you turn on continuous logical-log backup, the database server backs up each
logical log automatically when it becomes full. If you turn off continuous
logical-log backup, the logical-log files continue to fill. If all logical logs are filled,
the database server hangs until the logs are backed up. You can start continuous
logical log backups by setting the ALARMPROGRAM configuration parameter in
the onconfig file or by running an ON-Bar or ontape command.
Log salvage
When the database server is offline, you can perform a special logical-log backup,
called a log salvage. In a log salvage, the database server accesses the log files
directly from disk. The log salvage backs up any logical logs that have not yet
been backed up and are not corrupted or destroyed.
The log salvage enables you to recover all of your data up to the last available and
uncorrupted logical-log file and the last complete transaction.
Important: You lose transactions in logical-log files that are not backed up or
salvaged.
To illustrate, as the following figure shows, suppose you perform a level-0 backup
on Monday at 10 p.m. and then back up the logical logs on Tuesday at midnight.
On Wednesday at 11 a.m., you suffer a mishap that destroys your databases. You
would be unable to restore the transactions that occurred between midnight on
Tuesday and 11 a.m. on Wednesday unless you had continuous logical-log backup
setup.
If the disks that contain the storage spaces with the logical logs are damaged, the
transactions after midnight on Tuesday might be lost. To restore these transactions
from the last logical-log backup, try to salvage the logical logs before you repair or
replace the bad disk and then perform a cold restore.
Logical-log backup
Transactions
Time
Monday 10 P.M. Tuesday midnight Wednesday 11 A.M.
Restore systems
A restore recreates database server data from backed-up storage spaces and
logical-log files.
A restore recreates database server data that has become inaccessible because of
any of the following conditions:
v You need to replace a failed disk that contains database server data.
v A logic error in a program has corrupted a database.
v You need to move your database server data to a new computer.
v A user accidentally corrupted or destroyed data.
To restore data up to the time of the failure, you must have at least one level-0
backup of each of your storage spaces from before the failure and the logical-log
files that contain all transactions since these backups.
Physical restore
During a physical restore, ON-Bar or ontape restores the data from the most recent
level-0, level-1, and level-2 backups. When you suffer a disk failure, you can
restore to a new disk only those storage spaces with chunks that resided on the
failed disk. The following figure illustrates a physical restore.
Backup media
Logical restore
As the following figure shows, the database server replays the logical logs to
reapply any database transactions that occurred after the last backup. The logical
restore applies only to the physically restored storage spaces.
Root dbspace
INSERT...
Dbspace 1
Dbspace 2
For more information, see Chapter 6, “Restore data with ON-Bar,” on page 6-1 and
Chapter 13, “Restore with ontape,” on page 13-1.
Warm restore
As the following figure shows, a warm restore restores noncritical storage spaces.
A warm restore consists of one or more physical restores, a logical-log backup, and
a logical restore.
Backup media
Cold restore
As the following figure shows, a cold restore salvages the logical logs, and restores
the critical dbspaces (root dbspace and the dbspaces that contain the physical log
and logical-log files), other storage spaces, and the logical logs.
You can perform a cold restore onto a computer that is not identical to the one on
which the backup was performed by giving any chunk a new path name and
offset during the restore.
When restoring a standard backup, you must restore the logical logs by performing
a logical restore.
A cold restore starts by physically restoring all critical storage spaces, then the
noncritical storage spaces, and finally the logical logs. The database server goes
into recovery mode after the reserved pages of the root dbspace are restored. When
the logical restore is complete, the database server goes into quiescent mode. Use
the onmode command to bring the database server online.
Tip: If you mirror the critical dbspaces, you are less likely to have to perform a
cold restore after a disk failure because the database server can use the mirrored
storage space. If you mirror the logical-log spaces, you are more likely to be able to
salvage logical-log data if one or more disks fail.
Required: Cold restores are required for Enterprise Replication servers before
resuming replication.
Mixed restores
A mixed restore makes the critical data available sooner, however, the complete
restore takes longer because the logical logs are restored and replayed several
times, once for the initial cold restore and once for each subsequent warm restore.
The initial set of storage spaces you restore in the cold restore must include all
critical storage spaces in the server. To the extent that you do not restore all storage
spaces during the initial cold restore and avoid the time necessary to restore them,
The storage spaces that you do not restore during the cold restore are not available
until after you restore them during a warm restore, although they might not have
been damaged by the failure.
Related reference:
“Determine failure severity” on page 2-1
Normal log restore restores all of the available log file backups and applies the log
records. After the last available log is restored and applied, the log restore finishes.
Transactions that are still open are rolled back in the transaction cleanup phase,
then the server is brought into quiescent mode. After the server is quiesced, no
more logical logs can be restored.
With continuous log restore, instead of transaction clean up the server is put into
log restore suspended state after the last available log is restored. The restore client
(ontape or ON-Bar) exits and returns control to you. With the server in this state,
you can start another logical restore after additional logical logs become available.
As long as you start each log restore as a continuous log restore, you can continue
this cycle indefinitely.
One use of continuous log restore is to keep a second system available in case the
primary system fails. You can restore logical logs backed up on the primary system
on the secondary system as they become available. If the primary system fails, you
can restore remaining available logical logs on the secondary system and bring that
secondary system online as the new primary system.
For more information, see “Configuring a continuous log restore by using ON-Bar”
on page 6-9 and “Configuring continuous log restore with ontape” on page 13-9.
Related tasks:
“Configuring a continuous log restore by using ON-Bar” on page 6-9
“Configuring continuous log restore with ontape” on page 13-9
Important: The backup that ontape and ON-Bar produce are not compatible. You
cannot create a backup with ontape and restore it with ON-Bar, or vice versa.
Additional differences:
v Emergency boot files and sysutils database
The ontape utility does not use the sysutils database or the emergency boot
files.
v Simultaneous sessions
ON-Bar, with ISM, supports up to four simultaneous sessions per ISM
instance. The ontape utility supports two simultaneous sessions, one for
physical backup or restore, and one for log backup.
v Device support and storage management
The ontape utility supports remote backup devices on other hosts.
ON-Bar supports different sets of tape drives on various hardware platforms.
You can also use ON-Bar with the Tivoli storage manager or third-party storage
managers to obtain device support and storage management.
v Changing the logging mode of a database
You cannot change the logging mode for ON-Bar; however you can use the
ondblog utility to do this task when using ON-Bar.
You can also use the SQL administration API alternative, ALTER LOGMODE to
change the logging mode.
For details about each utility, see Chapter 5, “Back up with ON-Bar,” on page 5-1
and Chapter 12, “Back up with ontape,” on page 12-1.
Related reference:
Chapter 11, “Configure ontape,” on page 11-1
The following table shows recovery plans for failures with amounts of lost data.
Table 2-1. Sample recovery plans
Failure severity Data loss Suggested recovery plan
Small Noncritical data is lost. Restore of the data can wait until a
nonpeak time. Use a warm restore.
Medium The data that is lost is critical Perform a warm restore of this data as
for your business but does not soon as possible.
reside in a critical dbspace.
Large Critical dbspaces are lost. Use a mixed restore to restore the
critical data right away and a warm
restore to restore noncritical data during
off-peak hours.
Disaster All data is lost. Perform a cold or mixed restore as soon
as possible.
Related concepts:
“Warm, cold, and mixed restores” on page 1-5
How you use the data determines how you plan your backup schedule, as follows:
v Data usage
How do users use the data?
– Critical dbspaces (root dbspace and dbspaces that contain the physical log
and at least one logical-log file)
– Critical business application data
– Long-term data storage for legal or record-keeping reasons
– Data sharing among groups
– Test data
v Transaction Time
How much transaction time can be lost? Also, how long might it take to re-enter
lost transactions manually? For example, can you afford to re-enter all
transactions that occurred over the past three hours?
v Quantity and Distribution
How much data can you afford to lose? For example, you lost one fourth of
your customer profiles, or you lost the Midwest regional sales figures but the
West Coast figures are intact.
Ask the following questions to assist in deciding how often and when you want to
back up the data:
v Does your business have downtime where the system can be restored?
v If your system is 24x7 (no downtime), is there a nonpeak time where a restore
could occur?
v If a restore must occur during a peak period, how critical is the time?
v Which data can you restore with the database server online (warm restore)?
Which data must be restored offline (cold restore)?
v How many storage devices are available to back up and restore the data?
Schedule backups
You recovery strategy should include a schedule of backups. Tailor your backup
plan to the requirements of your system. The more often the data changes and the
more important it is, the more frequently you need to back it up.
The following table shows a sample backup plan for a small or medium-sized
system.
Table 2-2. Sample backup plan
Backup level Backup schedule
Complete backup (level-0) Saturday at 6 p.m.
Incremental backup (level-1) Tuesday and Thursday at 6 p.m.
Incremental backup (level-2) Daily at 6 p.m.
Level-0 backup of storage spaces that are updated Hourly
frequently
LBAC protection remains intact after you restore data with ON-Bar or ontape.
Also, consider your budget for storage media, disks, computers and controllers,
and the size of your network.
You must perform a level-0 backup of, at minimum, the root dbspace and the
modified storage spaces after you perform any of the following actions:
v Add or drop mirroring.
v Move, drop, or resize a logical-log file.
v Change the size or location of the physical log.
v Change your storage-manager configuration.
v Add, move, or drop a dbspace.
v Add, move, or drop a chunk to any type of storage space.
v Add, move, or drop a blobspace or sbspace.
For example, if you add a new dbspace dbs1, you see a warning in the message
log that asks you to perform a level-0 backup of the root dbspace and the new
dbspace. If you attempt an incremental backup of the root dbspace or the new
dbspace instead, ON-Bar automatically performs a level-0 backup of the new
dbspace.
Tip: Although you no longer need to back up immediately after adding a log file,
your next backup should be level-0 because the data structures have changed.
If you create a storage space with the same name as a deleted storage space,
perform a level-0 backup twice:
1. Back up the root dbspace after you drop the storage space and before you
create the storage space with the same name.
2. After you create the storage space, back up the root dbspace and the new
storage space.
You must perform a level-0 backup of the modified storage spaces before you
perform any of the following actions:
v Convert a nonlogging database to a logging database.
v Before you alter a RAW table to type STANDARD. This backup ensures that the
unlogged data is restorable before you switch to a logging table type.
Related reference:
“onbar -b syntax: Backing up” on page 5-2
Also consider temporary disk space needed for backup and restore. The database
server uses temporary disk space to store the before images of data that are
overwritten while backups are occurring and overflow from query processing that
occurs in memory.
When preparing to back up data, make sure that you correctly set the
DBSPACETEMP environment variable or parameter to specify dbspaces with
enough space for your needs. If there is not enough room in the specified
dbspaces, the backup will fail, root dbspace will be used, or the backup will fail
after filling the root dbspace.
How long your backup or restore takes depends on the following factors:
v The speed of disks or tape devices
The faster the storage devices, the faster the backup or restore time.
v The number of incremental backups that you want to restore if a disk or system
failure requires you to rebuild the database
Incremental backups use less storage space than full backups and also reduce
restore time.
v The size and number of storage spaces in the database
Backups: Many small storage spaces take slightly longer to back up than a few
large storage spaces of the same total size.
Restores: A restore usually takes as long to recover the largest storage space and
the logical logs.
v Whether storage spaces are mirrored
If storage spaces are mirrored, you reduce the chance of having to restore
damaged or corrupted data. You can restore the mirror at nonpeak time with the
database server online.
The following database server usage requirements affect your decisions about the
storage manager and storage devices:
v The amount and rate of transaction activity that you expect
v The number and size of logical logs
If you need to restore data from a database server with little transaction activity,
define many small logical logs. You are less likely to lose data because of
infrequent logical-log backups.
v How fast the logical-log files fill
Back up log files before they fill so that the database server does not hang.
v Database and table logging modes
When you use many nonlogging databases or tables, logical-log backups might
become less frequent.
Tip: If you compress row data before backing it up, compressing the backup
image with an external utility might not result in a smaller backup image.
The filter can be owned by anyone, but cannot have write access to non-privileged
users. Permission on the filters is the same as that of permission on any other
executable file that is called by an IBM Informix server or an Informix utility.
ON-Bar components
ON-Bar components include a command-line utility, catalog tables, an activity log,
and an emergency boot file. You use ON-Bar with a storage manager and the
XBSA shared library for the storage manager.
The following figure shows the ON-Bar and database server components:
v The storage spaces (dbspaces, blobspaces, and sbspaces) and logical logs from
the database server
v The sysutils database, which includes ON-Bar catalog tables
v The onbar and the onbar-d command-line utilities
v The XBSA shared library for the storage manager on your system
v The storage media for storing backups
v The ON-Bar activity log
v The ON-Bar emergency boot file
ON-Bar communicates with both the database server and the storage manager. You
use the onbar command to start a backup or restore operation. By default, ON-Bar
backs up and restores storage spaces in parallel. ON-Bar always processes log files
serially.
For a backup session, ON-Bar requests the contents of storage spaces and logical
logs from the database server and passes them to the storage manager. The storage
manager stores the data on storage media. For a restore session, ON-Bar requests
the backed up data from the storage manager and restores it on the database
server.
ON-Bar backs up the critical dbspaces first, then the remaining storage spaces, and
finally the logical logs. The critical dbspaces are the rootdbs and the dbspaces that
contain the logical logs and physical log.
ON-Bar also places the following critical files in the archive during backups:
v The onconfig file
v The ON-Bar emergency boot file: ixbar.servernum
v The server boot file: oncfg_servername.servernum
ON-Bar status and error messages are written to the activity log file: bar_act.log.
Each storage manager develops and distributes a unique version of the XBSA
shared library. You must use the version of the XBSA shared library provided with
the storage manager. For example, if you use ISM, also use the XBSA shared
library provided with ON-Bar. ON-Bar and the XBSA shared library must be
compiled the same way (32-bit or 64-bit).
ON-Bar uses XBSA to exchange the following types of information with a storage
manager:
Control data
ON-Bar exchanges control data with a storage manager to verify that
ON-Bar and XBSA are compatible, to ensure that objects are restored in the
correct order to the correct instance of the database server, and to track the
history of backup objects.
Backup or restore data
During backups and restores, ON-Bar and the storage manager use XBSA
to exchange data from specified storage spaces or logical-log files.
ON-Bar uses XBSA transactions to ensure data consistency. All operations included
in a transaction are treated as a unit. All operations within a transaction must
succeed for objects transferred to the storage manager to be restorable.
ON-Bar uses the following catalog tables in the sysutils database to track backup
and restore operations:
v The bar_server table tracks instances of the database server.
v The bar_object table tracks backup objects. A backup object is a backup of a
dbspace, blobspace, sbspace, or logical-log file.
v The bar_action table tracks all backup and restore attempts against each backup
object, except some log salvage and cold restore events.
v The bar_instance table describes each object that is backed up during a
successful backup attempt.
The onsmsync utility uses and maintains the following tables to track its
operations:
v The bar_ixbar table contains the history of all unexpired successful backups in
all timelines.
For a description of the content of these tables, see Chapter 9, “ON-Bar catalog
tables,” on page 9-1.
Important: Do not modify the emergency boot file. Doing so might cause ON-Bar
to select the wrong backup as part of a restore, possibly leading to data corruption
or system failure.
The file name for the boot file is ixbar.servernum, where servernum is the value of
the SERVERNUM configuration parameter.
The ON-Bar emergency boot file is in the $INFORMIXDIR/etc directory on UNIX and
in the %INFORMIXDIR%\etc directory on Windows. You can override the default path
and name of the boot file by changing the information specified in the
BAR_IXBAR_PATH configuration parameter.
ON-Bar backup and restore errors do not appear in standard output. If an error
occurs when you back up and restore data, check information in the ON-Bar
activity log
The ON-Bar activity log is in the /tmp directory on UNIX and in the
%INFORMIXDIR%\etc directory on Windows. You specify the location of the ON-Bar
activity log with the BAR_ACT_LOG configuration parameter.
Related reference:
“BAR_ACT_LOG configuration parameter” on page 16-3
Chapter 10, “ON-Bar messages and return codes,” on page 10-1
“View ON-Bar backup and restore performance statistics” on page 8-9
“onbar -m syntax: Monitoring recent ON-Bar activity” on page 5-9
ON-Bar script
The ON-Bar utility includes a shell script on UNIX and a batch script on Windows
for customizing backup and restore operations.
When you install ON-Bar with the database server, a default script is included. The
name and location of the script depends on the operating system:
When you issue ON-Bar commands from the command line, the arguments are
passed to the script, and then to the onbar_d utility.
Table 3-1. ON-Bar utilities
Utility Description
onbar_d utility Transfers data between the database server and the storage
manager.
The onbar command calls the onbar_d utility that starts the
onbar-driver. The onbar-driver starts and controls backup and
restore activities.
onsmsync utility Synchronizes the contents of the sysutils database, the emergency
boot files, and the storage manager catalogs. Use this utility to
purge backups that are no longer needed.
ondblog utility Changes the database-logging mode. The ondblog utility logs its
output in the ON-Bar activity log, bar_act.log.
archecker utility Verifies backups, and restores table-level data from an archive.
Related concepts:
“Overview of the archecker utility” on page 15-1
Related reference:
“The onsmsync utility” on page 8-4
IBM Informix Storage Manager (ISM) is included with your database server.
However, you can choose to use another storage manager that ON-Bar supports
and that is compatible with your storage devices.
The ISM server resides on the same computer as ON-Bar and the IBM Informix
database server; your storage devices are attached to this computer as well. ISM
can store data on simple tape drives, optical disk devices, and file systems. ISM
also performs the following functions:
v Configures up to four storage devices
v Adds, changes, and deletes administrative users
v Labels and mounts storage volumes on your storage devices
v Manages storage volumes
v Compresses and decompresses data
v Encrypts and decrypts data
TSM features
TSM efficiently manages disk, optical, and tape library resources. TSM provides the
following functions:
v Reduces network complexity with interfaces and functions that span network
environments.
v Increases administrator productivity by automating repetitive processes,
scheduling unattended processes, and administering TSM from anywhere in the
network
v Reduces risk of data loss with scheduled routine backups
Consider using IBM Tivoli Storage Manager (TSM) if IBM Informix Storage
Manager (ISM) does not support the features you require. For example, TSM
supports the following additional features:
v Creating policies to automate storage management and enforce data
management goals.
v Automating circulation of media through the storage management process.
v Implementing a progressive backup methodology so that files are backed up
incrementally to reduce network traffic, while recovery media is consolidated to
provide better performance.
v Using the Network Data Management Protocol to back up and restore file
systems stored on a network-attached storage file server.
To back up to an IBM Tivoli Storage Manager server, you must use the IBM
Informix Interface for TSM, which is part of the IBM Informix database server
installation. The interface contains a shared library that enables ON-Bar to
communicate with TSM.
Third-party storage managers might perform these functions, which are not
supported by the software manager included with ON-Bar:
v Schedule backups
v Support networked and distributed backups and restores
You can choose to use the IBM Informix Storage Manager (ISM), the IBM Tivoli
Storage Manager (TSM), or a third-party storage manager with ON-Bar. ISM is
installed with the database server. If use TSM, the XBSA shared library needed for
ON-Bar to communicate with TSM is bundled with the database Informix.
Ask the following interrelated questions to determine what storage devices you
need. For example, the speed and type of storage devices partly determine the
number of storage devices that you need.
v What type of storage devices do you need?
The transaction volume and the size of your database are major factors in
determining the type of storage devices that you need.
IBM Informix Storage Manager (ISM) supports simple tape devices such as QIC,
4 mm, 8 mm, DLT, optical devices, and disk backups. If ISM cannot manage the
storage devices that you need, you need to purchase a different storage manager.
For more information, see the IBM Informix Storage Manager Administrator's
Guide.
v What is the availability requirement for each device?
Is it important for your storage devices to allow random and sequential access?
If so, you cannot use tape storage devices.
v How many storage devices do you need?
ISM supports up to four devices per host.
The number of storage devices that you need depends on the storage devices
you have, how much transaction activity occurs on the database server, how fast
throughput is, how much time you can allow for backups, and other similar
factors.
The IBM Informix Primary Storage Manager and Tivoli Storage Manager do not
require an entry in the file.
The Tivoli Storage Manager does not require an entry in the file.
In the format, XBSA_ver is the release version of the XBSA shared library for the
storage manager, sm_name is the name of the storage manager, and sm_ver is the
storage-manager version. The maximum field length is 128 characters.
Before ON-Bar starts a backup or restore process with the Tivoli Storage Manager,
ISM, and third-party storage managers, ON-Bar calls the currently installed version
of the storage-manager-specific XBSA shared library to get its version number. If
this version is compatible with the current version of ON-Bar and is defined in the
sm_versions file, ON-Bar begins the requested operation.
Related tasks:
“Updating the storage-manager definition in the sm_versions file for TSM” on
page 4-7
“Configuring a third-party storage manager” on page 4-8
Related reference:
“Configuring ISM”
Configuring ISM
You can use the IBM Informix Storage Manager (ISM) with ON-Bar.
The ISM server is installed with the IBM Informix on UNIX or Windows. Several
database server instances can share one ISM instance.
Restriction: Install one copy of ISM on each computer to prevent possible conflicts
with the XBSA shared library. Do not run ISM and Legato NetWorker on the same
computer because they conflict with each other.
For instructions on how to set up ISM to work with ON-Bar, see the IBM Informix
Storage Manager Administrator's Guide.
Before you use ISM for your backups, perform these tasks:
v Set certain environment variables and configuration parameters
v Update the storage-manager definition in the sm_versions file.
Related reference:
“Storage-manager definitions in the sm_versions file” on page 4-1
If you use ISM, you can specify the volume pool names for storage spaces and
logical logs in the ISM_DATA_POOL and ISM_LOG_POOL configuration
parameters in the onconfig file. The ISM_DATA_POOL configuration parameter
specifies the volume pool that you use for backing up storage spaces. The
ISM_LOG_POOL configuration parameter specifies the volume pool that you use
for backing up logical logs.
If you do not set these configuration parameters, they default to the volume pool
names ISMData and then ISMLogs.
For information, see the IBM Informix Storage Manager Administrator's Guide.
Configuring TSM
To use IBM Tivoli Storage Manager (TSM) with IBM Informix databases, you must
install and configure the Tivoli Storage Manager client on your database server
computer and Tivoli Storage Manager on your storage computer.
You must also configure IBM Informix Interface for TSM and perform other TSM
configuration tasks on your IBM Informix database server computer.
To configure TSM:
1. Edit the TSM client options files.
2. Assign a TSM management class for the server to use for backups.
3. Set the IBM Informix Interface for TSM environment variables.
4. Register with the TSM server.
5. Initialize the IBM Informix Interface for TSM.
6. Optional. Configure ON-Bar to support optional TSM features.
On UNIX systems, edit both the dsm.opt and the dsm.sys files as the root user:
v Specify the TSM server to use in the client user options file, dsm.opt.
v Identify the TSM server name, communication method, and server options in the
client system options file, dsm.sys.
Use the sample dsm.opt.smp and dsm.sys.smp files distributed with the TSM API to
help you get started quickly.
On Windows systems, specify the TMS server name, communication method, and
server options in the dsm.opt file.
See TSM Installing the Clients and TSM Trace Facility Guide for information
regarding options you can specify in these files.
You can edit the IBM Tivoli Storage Manager (TSM) client user options file,
dsm.opt. This file must refer to the correct TSM server instance, as listed in the
dsm.sys file.
You can edit the IBM Tivoli Storage Manager (TSM) client systems options file,
dsm.sys. This file must refer to the correct TSM server address and communication
method.
The following TSM options are the most important to set in the dsm.sys file:
SERVERNAME
Specifies the name that you want to use to identify a server when it is
referred to in the dsm.opt file and to create an instance that contains
options for that server.
COMMMETHOD
Identifies the communication method.
The SERVERNAME option in the dsm.opt and dsm.sys files define server instance
names only. The TCPSERVERADDRESS option controls which server is contacted.
You can set up multiple server instances in the dsm.sys file. See the Tivoli Storage
Manager Backup-Archive Client Installation and User's Guide for information about
multiple server instances.
Related concepts:
“Configuring ON-Bar for optional TSM features” on page 4-7
Related reference:
“IFX_BAR_USE_DEDUP environment variable” on page 16-14
The INCLUDE option is placed in the include-exclude options file. The file name
of the include-exclude options file is in the client system options file (dsm.sys).
For more information, see the Tivoli Storage Manager Backup-Archive Client
Installation and User's Guide.
where the number 55 is the value of the SERVERNUM parameter in the onconfig
file.
For error log files, create a directory for the error logs to be
created in, then set the DSMI_LOG environment variable to that
directory. The user informix or the backup operator should have
write permission on this directory.
The following example shows how to set up these environment variables for
Solaris 32-bit if the TSM API is installed in the /opt/Tivoli/tsm/client/api
directory:
export DSMI_CONFIG=/opt/Tivoli/tsm/client/api/bin/dsm.opt
export DSMI_DIR=/opt/Tivoli/tsm/client/api/bin
export DSMI_LOG=/home/user_a/logdir
The following example shows how to set up these environment variables for
Windows if the TSM API is installed in the C:\Tivoli\TSMClient\api directory:
set DSMI_CONFIG=C:\Tivoli\TSMClient\api\BIN\dsm.opt
set DSMI_DIR=C:\Tivoli\TSMClient\baclient
set DSMI_LOG=C:\logdir
After the IBM Informix Interface for TSM node is registered with a TSM server,
you can begin using the IBM Informix Interface for TSM to back up and restore
your IBM Informix storage spaces and logical logs. If your workstation has a node
name assigned to the TSM backup-archive client, you should have a different node
name for IBM Informix Interface for TSM. For information about performing the
registration process, see the Tivoli Storage Manager Backup-Archive Client Installation
and User's Guide.
You must run the txbsapswd program as user root before using IBM Informix
Interface for TSM.
Before ON-Bar starts a backup or restore process, it calls the currently installed
version of the storage-manager-specific XBSA shared library to get its version
number. If this version is compatible with the current version of ON-Bar and is
defined in the sm_versions file, ON-Bar begins the requested operation.
The following example shows the Tivoli Storage Manager definition in the
sm_versions file:
1|5.3|tsm|5
Related reference:
“Storage-manager definitions in the sm_versions file” on page 4-1
Apply all patches and updates to TSM before you use the following TSM features.
Deduplication
Deduplication eliminates redundant data in backups. To enable Informix
support for deduplication, set the IFX_BAR_USE_DEDUP environment variable
in the Informix environment and restart the database server. Update the
TSM client systems option file.
Large transfer buffer size
The default transfer buffer size is 64 KB. Set the BAR_XFER_BUF_SIZE
configuration parameter to specify a transfer buffer of up to 65 MB.
To limit the transfer buffer size to 64 KB regardless of the value of the
BAR_XFER_BUF_SIZE configuration parameter, set the
IFX_NO_LONG_BUFFERS environment variable to 1.
Replicate, import, and export backup objects
Replicating, importing, or exporting backup objects between TSM servers
requires unique IDs for backup objects. ON-Bar automatically stores IDs in
the metadata of backup objects that are unique for all TSM server with
version 11.70.xC8 or later.
For the list of certified storage managers for your ON-Bar version, consult your
marketing representative.
Important: Some storage managers let you specify the data to back up to specific
storage devices. Configure the storage manager to back up logical logs to one
device and storage spaces to a different device for more efficient backups and
restores.
UNIX
For example, if you are using ISM, you can do either of the following:
v Link $INFORMIXDIR/lib/ibsad001.so to $INFORMIXDIR/lib/libbsa.so
v Set BAR_BSALIB_PATH to $INFORMIXDIR/lib/libbsa.so
For example, if you are using TSM, you can do either of the following:
v Link $INFORMIXDIR/lib/ibsad001.so to $INFORMIXDIR/lib/libtxbsa.so
v Set BAR_BSALIB_PATH to $INFORMIXDIR/lib/libtxbsa.so
Windows
On Windows, because no default XBSA shared library name exists, you must
specify its name and location in the BAR_BSALIB_PATH configuration parameter.
For example:
v If you are using ISM, set BAR_BSALIB_PATH to %ISMDIR%\bin\libbsa.dll.
v If you are using TSM, set BAR_BSALIB_PATH to %DIR%\bin\libtxbsa.dll.
If you are using a third-party storage manager, ON-Bar must use the version of the
XBSA library that the storage-manager manufacturer provides. For more
information, see “BAR_BSALIB_PATH configuration parameter” on page 16-4 and
your release notes.
Important: To set the path name of the XBSA library with the BAR_BSALIB_PATH
configuration parameter in the onconfig file, specify the absolute path name. If you
specify a relative path name, then the following message is written to the ON-Bar
activity log: BAR_BSALIB_PATH in ONCONFIG is not an absolute path name.
If not, you need to install a validated storage manager before you perform backups
with ON-Bar.
You can configure the behavior of ON-Bar by setting the following configuration
parameters and environment variable.
Table 4-2. ON-Bar configuration parameters and environment variable
Behavior Configuration parameters
Control the number and size of data buffers “BAR_NB_XPORT_COUNT configuration
and the number of parallel processes. parameter” on page 16-9
“BAR_XFER_BUF_SIZE configuration
parameter” on page 16-12
“IFX_BAR_NO_LONG_BUFFERS
environment variable” on page 16-13
“BAR_MAX_BACKUP configuration
parameter” on page 16-8
Set the debugging level and the location of “BAR_DEBUG configuration parameter” on
debug log file. page 16-5
“BAR_DEBUG_LOG configuration
parameter” on page 16-6
Change the path of the ON-Bar boot file. “BAR_IXBAR_PATH configuration
parameter” on page 16-7
Maintain a history of expired backups. “BAR_HISTORY configuration parameter”
on page 16-7
Change the location and contents of ON-Bar “BAR_IXBAR_PATH configuration
activity log. parameter” on page 16-7
Maintain a history of expired backups. “BAR_ACT_LOG configuration parameter”
on page 16-3
“BAR_PROGRESS_FREQ configuration
parameter” on page 16-10
“BAR_PERFORMANCE configuration
parameter” on page 16-9
Set automatic retrying of failed back ups or “BAR_RETRY configuration parameter” on
restores. page 16-11
Allow a failed restore to be restarted. “RESTARTABLE_RESTORE configuration
parameter” on page 16-19
Increase backup size estimate sent to the “BAR_SIZE_FACTOR configuration
storage manager. parameter” on page 16-11
Extend the time an RS secondary server “BAR_CKPTSEC_TIMEOUT configuration
waits for a checkpoint during an external parameter” on page 16-5
backup.
Configure continuous log backup. ALARMPROGRAM
“RESTORE_FILTER configuration
parameter” on page 16-19
Optimize the deduplication capabilities of “IFX_BAR_USE_DEDUP environment
storage managers. variable” on page 16-14
Disable the ability to replicate, import, or “IFX_TSM_OBJINFO_OFF environment
export backup objects among TSM servers. variable” on page 16-15
Force the use of the sm_versions file. “IFX_BAR_NO_BSA_PROVIDER
environment variable” on page 16-13
ON-Bar security
By default, only the informix or root users on UNIX system or members of the
Informix-Admin group on Windows systems can run ON-Bar commands.
After you verify that ON-Bar and your storage manager are set up correctly, run
ON-Bar on your test database to make sure that you can back up and restore data.
For more information, follow the instructions in Chapter 5, “Back up with
ON-Bar,” on page 5-1.
The following table lists the files that ON-Bar, IBM Informix Storage Manager
(ISM), and IBM Tivoli Storage Manager (TSM) use and the directories where the
files are. These names and locations change if you set up the onconfig file to
values different from the defaults.
Table 4-3. List of files that ON-Bar, ISM, and TSM use
File name Directory Purpose
ac_config.std UNIX: $INFORMIXDIR/etc Template for archecker parameter values.
DIR%\bin
oncfg_servername.servernum $INFORMIXDIR/etc Configuration information for ON-Bar restores.
%ISM%\bin
sm_versions $INFORMIXDIR/etc Identifies the version of ISM or a third-party storage
manager.
%INFORMIXDIR%\etc
To update the storage-manager version, edit the
sm_versions file directly.
xbsa.messages $INFORMIXDIR/ism/applogs XBSA library call information.
You can customize ON-Bar and storage manager commands in a shell or batch
script. You can call ON-Bar from a job-scheduling program.
Related reference:
“Customizing ON-Bar and storage-manager commands” on page 8-1
When you back up a storage space, ON-Bar also backs up the following critical
files:
v The onconfig file
v The ON-Bar emergency boot file: ixbar.servernum
v The server boot file: oncfg_servername.servernum
You must restore these files if you need to replace disks or if you restore to a
second computer system (imported restore).
Tip: Even though ON-Bar includes the critical files with the files it backs up, it is a
good practice to also include the critical files in your system archive. Having the
critical files included in both the IBM Informix and system archives gives you
more options if you need them.
In addition to the critical files, you must also manually back up the following
administrative files:
v The sm_versions file
v Storage-manager configuration and data files
v Simple-large-object data in blobspaces that are stored on disks
v Simple-large-object data in blobspaces that are stored on disks or optical platters
v Externally stored data such as external tables that a DataBlade® maintains
Although ON-Bar does not back up the following items, ON-Bar automatically
re-creates them during a restore. You do not need to make backup copies of these
files:
v The dbspace pages that are allocated to the database server but that are not yet
allocated to a tblspace extent
v Mirror chunks, if the corresponding primary chunks are accessible
v Temporary dbspaces
ON-Bar does not back up or restore the data in temporary dbspaces. Upon
restore, the database server re-creates empty temporary dbspaces.
The bar_act.log contains information about which critical files were backed up.
The following example shows that the ON-Bar emergency boot file, ixbar.0, is
backed up:
Begin backup of critical file ’/opt/informix-11.70.fc7/etc/ixbar.0’.
Completed backup of critical file ’/opt/informix-11.70.fc7/etc/ixbar.0’
To run ON-Bar commands, you must be user root, user informix, a member of the
bargroup group on UNIX, or a member of the Informix-Admin group on
Windows.
v “Usage” on page 5-5
v “Example: Back up a whole system” on page 5-6
onbar -b
-L 0 -O -cf yes
1 no
2 only
-p
-f filename
dbspace_list
-w
-l
-C
-c
-s
-F
Backs up the storage spaces and logical logs, including the current logical
log.
dbspace_list Specifies the storage spaces to be backed up, separated by blank spaces.
Use this option to avoid entering a long list of storage spaces every time
that you back up.
For more information, see “List of storage spaces in a file” on page 5-7.
-F Performs a fake backup
Use this option to back up logical logs when blobspaces are offline.
If a log backup occurs when blobspaces are offline, return code 178
displays in the ON-Bar activity log.
A warning message is written to the activity log listing the log unique ID
of the latest log file that is required for a restore of the storage spaces. Use
this option if logical logs are being continuously backed up. If necessary, a
log switch is initiated, so that this log can be backed up. If the current log
is already newer than the log with the archive checkpoint of the last
storage space, then no log switch is initiated.
-s Salvages any logical logs that are still on disk after a database server
failure. You can run the onbar -l -s command while the server is offline.
If possible, use this option before you replace a damaged disk. If you use
onbar -r to perform a cold restore on an undamaged disk, ON-Bar
automatically salvages the logical logs.
-w Backs up a whole system, which includes all storage spaces and logical logs
based on a single checkpoint.
The time of the backup is stored with the backup information. The data in
all storage spaces is consistent in a whole-system backup, therefore, you do
not need to restore the logical logs to make the data consistent. If you do
not save the logical logs, you must use the -w option.
Usage
Before you back up your data, make sure that your data is consistent by running
the oncheck -cD command.
To run ON-Bar commands, you must be user root, user informix, or a member of
the bargroup group on UNIX, or a member of the Informix-Admin group on
Windows. For more information, see “ON-Bar security” on page 4-11.
You can back up storage spaces and logical logs when the database server is in
online, quiescent, or fast-recovery mode.
The storage-space chunks can be stored on raw disk storage space, in cooked files,
or on an NTFS file system (Windows).
Only online storage spaces are backed up. Use the onstat -d command to
determine which storage spaces are online. During a backup, if ON-Bar encounters
a down dbspace, it skips it and later returns an error. If a storage space is offline,
restart the backup when the storage space is back online.
After you begin the backup, monitor its progress in the ON-Bar activity log and
database server message log.
You can either back up the logical logs separately or with storage spaces. Back up
the logical logs as soon as they fill so that you can reuse them and to protect
against data loss if the disks that contain the logs are lost. If the log files fill, the
database server pauses until you back up the logical logs. You can either back up
the logical logs manually or start a continuous logical-log backup by running the
onbar -b -C command. Logical-log backups are always level 0. After you close the
current logical log, you can back it up.
If you are running continuous logical log backup and then start a whole system
backup, the ON-Bar process attempts to save the logical logs. Because the
continuous logical log backup is running, an error message is returned indicating
that a logical log backup is already running, and the whole system backup returns
a non-zero error code. In this case the logical logs are backed up only one time. To
avoid the error, create a physical backup with the onbar -b -w -p command.
The following command performs a level-0 whole system backup after taking a
checkpoint of all online storage spaces and logical logs:
onbar -b -w
The following command performs a standard, level-0 backup of all online storage
spaces and used logical logs:
onbar -b
The following sample file named listfile3 contains a list of storage spaces to be
backed up:blobsp2.1, my_dbspace1, blobsp2.2, dbsl.1, rootdbs.1, and dbsl.2.
blobsp2.1
# a comment ignore this text
The following command backs up the storage spaces listed in the listfile3 file:
onbar -b -f listfile3
The following command backs up all storage spaces without backing up any
logical logs:
onbar -b -p -L 0
A warning message is written to the ON-Bar activity log file stating that log file
backup was not initiated. The message also contains the log unique ID of the latest
log file that is required for a restore of the storage spaces. The latest required log
file contains the archive checkpoint of the last dbspace backed up.
Example message:
2011-12-14 09:30:35 14277 14275 (-43354) WARNING: Logical logs were
not backed up as part of this operation. Logs through log unique ID 9
are needed for restoring this backup. Make sure these logs are backed
up separately.
Related tasks:
“Configuring a continuous log restore by using ON-Bar” on page 6-9
“Replacing disks during a restore” on page 6-14
“Preparing to back up data” on page 5-1
Related reference:
“Plan a backup system for a production database server” on page 2-3
“ON-Bar security” on page 4-11
The filename value can be any valid UNIX or Windows file name:
v Simple file names, for example: listfile_1)
v Relative file names, for example: ../backup_lists/listfile_2 or
..\backup_lists\listfile2
v absolute file names, for example: /usr//backup_lists/listfile3 or
c:\\backup_lists\listfile3
Always keep the volumes from the ISMLogs pool mounted to ensure that a storage
device is always available to accept logical-log data. If the volume is not mounted,
the backup pauses. For more information about using devices and ISM commands,
see the IBM Informix Storage Manager Administrator's Guide.
During the backup operation, ISM creates save sets of the backed up data and
enters information about the backed up data in the ISM catalog. You can also use
the ism_catalog -create_bootstrap command to back up the ISM catalog:
If you use the onbar script to back up storage spaces and logical logs, it backs up
the ISM catalog automatically. If you call onbar_d directly, you must use the
ism_catalog -create_bootstrap command.
Therefore, the media or volume containing the first bootstrap creation is always
necessary in order to restore the bootstrap successfully.
To avoid the need for the first media or volume during bootstrap restore, a full
bootstrap backup must be performed every time. The level must be specified
explicitly by using, the underlying savegrp command that ism_catalog
-create_bootstrap calls.
To perform a full backup of the ISM catalog every time, run the
$INFORMIXDIR/bin/savegrp -O -l full ISMData command as the user root.
In this command, -O is a capital O (not a zero), and ISMData is the pool name
where the bootstrap data is saved.
You can edit the $INFORMIXDIR/bin/onbar shell script to replace the ism_catalog
-create_bootstrap command with the savegrp command.
Redirect the output (both stdout and stderr) of the savegrp command to the
ON-Bar activity log file (specified by the BAR_ACT_LOG configuration parameter
in onconfig file).
Backing up blobspaces
You can back up blobspaces in a database that uses transaction logging.
Before you back up a new blobspace, make sure that the log file that recorded the
creation of the blobspace is no longer the current log file. You can run the onstat -l
command to verify the logical-log status.
When users update or delete simple large objects in blobspaces, the blobpages are
not freed for reuse until the log file that contains the delete records is freed. To free
the log file, you must back it up.
To back up blobspaces:
1. Verify the logical-log status by running the onstat -l or xctl onstat -l command.
2. Switch to the next log file by running the onmode -l command.
3. Back up the logical logs:
v If the blobspace is online, run the onbar -b -l -c command.
v If the blobspace is offline, run the onbar -b -l -O or onbar -b -O command. If
this backup is successful, ON-Bar returns 178.
4. Back up the blobspaces by running the onbar -b or onbar -b -w command.
Related reference:
onstat -L command: Print the number of free locks (Administrator's Reference)
20
onbar -m
lines 5
-r
seconds
Related concepts:
“bar_act.log file: ON-Bar activity log” on page 3-4
Related reference:
Chapter 10, “ON-Bar messages and return codes,” on page 10-1
“Message format in the ON-Bar message log” on page 10-1
“ON-Bar security” on page 4-11
Example
FROM
bar_action A,
bar_instance I,
bar_object O
WHERE
A.act_aid = I.ins_aid AND
A.act_oid = O.obj_oid AND
A.act_oid = I.ins_oid AND
O.obj_type in ("R", "CD", "ND", "L")
GROUP BY 1,2,3,5,6,7,8,9
ORDER BY Ifx_Time, Backup_ID) AS view_list_backups
To run ON-Bar commands, you must be user root, user informix, a member of the
bargroup group on UNIX, or a member of the Informix-Admin group on
Windows.
v “Usage” on page 5-12
v “Example: Print a specific transaction” on page 5-12
v “Example: Print multiple logical log files” on page 5-13
onbar -P -n unique_id
starting_id-ending_id
-l -q -b -c -u username -t tblspace_num
-x transaction_num
Usage
To view the backed-up logical logs, the storage manager must be running.
The following command prints information about a single transaction that was
performed by the user informix against the tblspace 1048722 and is contained in
the logical log file 2:
onbar -P -n 2 -l -q -b -u "informix" -t 1048722 -x 1
The following command prints the logical log records for the logical logs files that
have IDs of 2, 3, 4, 5, 10, 11, and 12:
onbar -P -n 2-5 -n 10-12
Related reference:
onstat -l command: Print physical and logical log information (Administrator's
Reference)
onstat -L command: Print the number of free locks (Administrator's Reference)
SYSTABLES (SQL Reference)
“ON-Bar security” on page 4-11
To run ON-Bar commands, you must be user root, user informix, a member of the
bargroup group on UNIX, or a member of the Informix-Admin group on
Windows.
Verify backups
onbar -v
-p -t "time" -f filename
space
-w
If you enter more than one storage-space name, use a space to separate the
names.
Use this option to avoid entering a long list of storage spaces every time
that you verify them.
You can use any valid UNIX or Windows path name and file name. For
the format of this file, see “List of storage spaces in a file” on page 5-7.
How you enter the time depends on your current GLS locale convention. If
the GL_DATETIME environment variable is set, you must specify the date and
time according to that variable. If the GLS locale is not set, use ANSI-style
date format: YYYY-MM-DD HH:MM:SS.
-w Verifies a whole-system backup.
Usage
The onbar -v command runs the archecker utility. The archecker utility verifies
that all pages required to restore a backup exist on the media in the correct form.
After you successfully verify a backup, you can restore it safely.
When you verify a backup, ON-Bar writes summary messages to the bar_act.log
that report which storage spaces were verified and whether the verification
succeeded or failed. The archecker utility writes detailed messages to the
ac_msg.log. IBM Software Support uses the ac_msg.log to diagnose problems with
backups and restores.
The onbar -v command cannot verify the links between data rows and simple
large objects in a blobspace. Use the oncheck -cD command instead to verify the
links in a blobspace.
The following command verifies the backed-up storage spaces that are listed in the
file bkup1:
onbar -v -f /usr/backups/bkup1
The following examples show messages about verification in the ON-Bar activity
log:
If the backup is verified successfully, these files are deleted. If the backup fails
verification, these files remain. Copy them to another location so that IBM Software
Support can review them.
If your database server contains only dbspaces, use the following formula to
estimate the amount of temporary space in KB for the archecker temporary files:
space = (130 KB * number_of_chunks) + (pagesize * number_of_tables) +
(.05 KB * number_of_logs)
For IBM Informix, if your database server contains blobspaces or sbspaces, use the
following formula to estimate the amount of temporary space for the archecker
temporary files:
space = (130 KB * number_of_chunks) + (pagesize * number_of_tables) +
(.05 KB * number_of_logs) + (pagesize * (num_of_blobpages/252))
For example, you would need 12.9 megabytes of temporary disk space on a
50-gigabyte system with a page size of 2 KB. This system does not contain any
blobspaces, as the following statement shows:
13,252 KB = (130 KB * 25 chunks) + (2 KB * 5000 tables) +
(.05 KB * 50 logs) + (2 KB * 0)
Verification failures
The verification of a backup can fail for various reasons. If a backup fails
verification, do not attempt to restore it.
The causes of a verification failure are unpredictable and range from corruption of
the database server to a failed restore because ON-Bar cannot find the backup
object on the storage manager. In fact, the restore might appear to be successful but
it hides the real problem with the data or media.
If the pages are corrupted, the problem is with the databases rather than with the
backup or the media.
Run oncheck -cd on any tables that produce errors and then redo the backup and
verification. To check extents and reserved pages, run oncheck -ce and oncheck
-cr.
In this case, all the data is correct, but some of the backup control information is
incorrect, which might cause problems with the restore. Ask IBM Software Support
for assistance.
When a backup is missing data, it might not be recoverable. After a data loss, try
to restore from an older backup. Then restore the current logical logs.
There are cases where archecker returns “success” to ON-Bar but shows “failure”
in the archecker message logs. This situation occurs when archecker verifies that
ON-Bar backed up the data correctly, but the database server data was invalid or
inconsistent when it was backed up.
Before you restore data, use the pre-restore checklist to determine if whether a
restore is needed and to prepare for a restore.
Pre-restore checklist
Use this checklist to determine if a restore is necessary and to prepare for a restore.
The following table describes onstat -d command output about chunk status and
the actions required to solve the problems. The chunk status information is in the
second position of the flags column in the first (storage spaces) and second
(chunks) sections of the output.
Table 6-1. Chunk flag descriptions and required actions
chunk flag Storage space or chunk state Action required
(No flag) Storage space no longer exists. Perform a point-in-time cold restore to a time
before the storage space was dropped.
D Chunk is down or storage space is disabled. Perform a warm restore of the affected storage
space.
I Chunk is physically restored, but needs a Perform a logical restore.
logical restore.
L Storage space is being logically restored. Try the logical restore again.
N Chunk is renamed and either down or Perform a warm restore of the chunk when the
inconsistent. physical device is available.
O Chunk is online. No action required.
P Storage space is physically restored. Perform a logical restore, if one is not already
in progress.
R Storage space is being restored. Perform a physical or logical restore.
X Storage space or chunk is newly mirrored. No action required.
Related reference:
onstat -d command: Print chunk information (Administrator's Reference)
“onbar -r syntax: Restoring data” on page 6-3
You can set the retention period for either a save set or volume. Unless all the save
sets on the volume are expired, you can use ON-Bar to restore it.
After the retention period for a save set expires, ON-Bar can no longer restore it.
To recreate an expired save set, use the ism_catalog -recreate from command.
If you set the retention period for a volume, ISM retains the save sets until all the
save sets on that volume are expired. To recover an expired volume, use the
ism_catalog -recover from command.
Related reference:
ISM command-line utilities (Informix Storage Manager Guide)
If you drop a dbspace or mirror device after a level-0 backup, the dbspace or
mirror device must be available to the database server when you begin the restore.
If the storage device is not available, the database server cannot write to the chunk
and the restore fails.
If you add a chunk after your last backup, the chunk device must be available to
the database server when it rolls forward the logical log.
To run ON-Bar commands, you must be user root, user informix, a member of the
bargroup group on UNIX, or a member of the Informix-Admin group on
Windows.
v “Usage” on page 6-6
v “Example: Perform a whole-system restore” on page 6-7
v “Example: Restore specific storage spaces” on page 6-7
v “Example: Perform a warm restore in stages” on page 6-7
v “Example: Point-in-time restore” on page 6-7
v “Example: Point-in-time restore with a French locale” on page 6-8
v “Example: Point-in-time restore in stages” on page 6-8
v “Example: Restore a dropped storage space and chunks” on page 6-8
Perform a restore
onbar -r
-w -t "time" -O -f filename
-p -n log Rename chunks
-e
space
-l
-C
-X
-t "time"
-n log
Rename chunks:
-rename -f filename
In a cold restore, the -r option restores all storage spaces and salvages and
restores the logical logs. In a warm restore, the -r option restores all storage
spaces that are offline and restores the logical logs.
ON-Bar restores only the storage spaces listed. If the database server is
offline, you must list all the critical dbspaces. You cannot specify temporary
spaces.
-C Continuously restores logical logs from the current logical log tape without
sending prompts to mount the tape.
The server is placed in suspend log restore state, and the command exits
after the last applicable log is restored. The server sends a prompt if a log
spans tapes. The configuration parameter RESTARTABLE_RESTORE does
not affect continuous log restoration.
-e Specifies an external restore. Run the onbar -r -e command after you
externally restore the storage spaces. Marks storage spaces as physically
restored, restores the logical logs, and brings the storage spaces online.
-f filename Specifies the path and file name of a text file that lists the storages spaces
to restore or rename.
For more information, see “List of storage spaces in a file” on page 5-7.
-l Specifies a logical restore only. Restores and rolls forward the logical logs.
The logical restore applies only to those storage spaces that are already
physically restored.
Important: To improve performance, replay logical-log transactions in
parallel during a warm restore. Use the ON_RECVRY_THREADS
configuration parameter to set the number of parallel threads. To replay
logical-log transactions in parallel during a cold restore, use the
OFF_RECVRY_THREADS configuration parameter. For more information,
see your IBM Informix Performance Guide.
-n log Indicates the unique ID of the last logical log to be restored in a cold
restore. The database server must be offline.
You must follow a physical restore with a logical restore before data is
accessible unless you use a whole-system restore. This option turns off
automatic log salvage before a cold restore. If the LTAPEDEV configuration
parameter is set to /dev/null or NUL, you must use the -p option during a
restore.
-p old_path Specifies the path of the chunk to be renamed. Use with the -rename
option.
-rename Renames one or more chunks during a cold restore. The database server
must be offline.
All storage spaces specified are restored to the same point in time.
However, if you perform a physical restore followed by a logical restore,
the logical restore can be to a later point in time. For example you might
detect that your current backup is corrupted, and that you need to restore
the previous backup. In this case, start your physical restore with the
timestamp of your previous backup, and subsequently start the logical
recovery to a more recent timestamp.
To determine the appropriate date and time for the point-in-time restore,
use the onlog utility. The onlog utility output shows the date and time of
the committed transactions in the logical log. All data transactions that
occurred after the time you specify in the restore command are lost.
Use quotation marks around the date and time. The format for the English
locale is yyyy-mm-dd hh:mm:ss. If the GL_DATETIME environment variable is
set, you must specify the date and time according to that variable.
Usage
You can restore storage spaces stored in both raw and cooked files. If your system
contains primary and mirror storage spaces, ON-Bar writes to both chunks
simultaneously during the restore, except for an external restore. You cannot
specify to restore temporary spaces. When you restore the critical dbspaces (for
example, the root dbspace), the database server recreates the temporary dbspaces,
but they are empty.
You can restore noncritical storage spaces in a warm restore, when the database
server is online, in the following circumstances:
v The storage space is online, but one of its chunks is offline, recovering, or
inconsistent.
v The storage space is offline or down.
Tip: For faster performance in a restore, assign separate storage devices for
backing up storage spaces and logical logs. If physical and logical backups are
mixed together on the storage media, it takes longer to scan the media during a
restore.
By default, ON-Bar restores the latest backup. If you do not want to restore the
latest backup, you can restore from an older backup: for example, when backup
verification failed or the backup media was lost. You can perform a point-in-time
restore or a point-in-log restore. Alternatively, you can expire a bad backup in the
storage manager, run the onsmsync command, and then restore from the older
backup. If you accidentally drop a storage space, you can use a point-in-time
restore or a point-in-log restore to recover it.
You can force a restore of online storage spaces (except critical dbspaces) by using
the -O option. The database server automatically shuts down each storage space
before it starts to restore it. Taking the storage space offline ensures that users do
not try to update its tables during the restore process.
You can rename chunks by specifying new chunks paths and offsets during a cold
restore with ON-Bar. This option is useful if you need to restore storage spaces to a
different disk from the one on which the backup was made. You can rename any
type of chunk, including critical chunks and mirror chunks.
A whole-system restore is a cold restore and must be performed while the server is
offline. The following command restores a whole-system backup:
onbar -r -w
The following example restores two specific storage spaces, fin_dbspace1 and
fin_dbspace2:
onbar -r fin_dbspace1 fin_dbspace2
The following commands perform a physical restore, back up logical logs, and
perform a logical restore:
onbar -r -p
onbar -b -l
onbar -r -l
The following command restores database server data to its state at a specific date
and time:
In this example, the restore replays transactions that committed on or before the
specified time, including any transactions with a commit time of 11:35:57.
Transactions in progress but not committed by 11:35:57 are rolled back.
The default date and time format for the French locale, fr_fr.8859-1, uses the
format "%A %.1d %B %iY %H:%M:%S."
The following command restores the data to a specific point in time that is
formatted for the French locale:
onbar -r -t "Lundi 6 Juin 2011 11:20:14"
You can set GL_DATETIME to a different date and time format that uses the date,
month, two-digit year, hours, minutes, and seconds. For example:
%.1d %B %iy %H:%M:%S
The following commands perform a physical restore and a logical restore to the
same point in time:
onbar -r -p -t "2011-05-10 11:35:57"
onbar -r -l -t "2011-05-10 11:35:57"
Suppose that a transaction dropped a storage space named dbspace1 and deleted
chunks at the time 2011-05-10 12:00:00. The following command restores the
storage space and recreates the deleted chunks while the server is offline:
onbar -r -t "2011-05-10 11:59:59" -O
Related tasks:
“Restoring when a backup is missing data” on page 5-17
“Replacing disks during a restore” on page 6-14
Related reference:
“Storage space status and required actions” on page 6-2
“External restore commands” on page 7-6
“ON-Bar security” on page 4-11
“onbar -RESTART syntax: Restarting a failed restore” on page 6-19
If you try to perform a cold restore without a backup, data in the storage spaces
that were not backed up are lost.
The version of IBM Informix must be identical on both the primary and secondary
systems.
In a mixed restore, you first perform a cold restore of the critical dbspaces (the root
dbspace and the dbspaces that contain the physical and logical logs) and the
dbspaces containing your urgent data. Because you do not restore all dbspaces,
you can bring the server online faster. You then restore the remaining storage
spaces in one or more warm restores.
Examples
Example 1: Simple mixed restore
A database server has five dbspaces in addition to the root dbspace:
logdbs, dbs_1, dbs_2, dbs_3, and dbs_4. The logical logs are stored in
logdbs and the physical log is in the root dbspace. The critical dbspaces
ON-Bar backs up and restores physical, not logical, entities. Thus, ON-Bar cannot
restore a particular database or a particular set of tables. Instead, ON-Bar restores a
particular set of storage spaces. It is up to you to track what is stored in those
storage spaces.
For example, consider a database with the catalogs in the dbspace cat_dbs:
create database mydb in cat_dbs with log;
If you need to restore the server, you cannot access all of the data in the example
database until you restore the dbspaces containing the database catalogs, table
data, and index: in this case, the dbspaces cat_dbs, tab_dbs_1, tab_dbs_2, and
idx_dbs.
To simplify the management and tracking of your data, divide your set of
dbspaces into subsets in which you store data of a particular urgency. When you
create your database objects, place them in dbspaces appropriate to their urgency.
For example, if you have data with three levels of urgency, you might want to
Chapter 6. Restore data with ON-Bar 6-11
place all the objects (database catalogs, tables, and indexes) associated with your
most urgent data in a particular set of dbspaces: for example, urgent_dbs_1,
urgent_dbs_2, ...urgent_dbs_n. You would place all the objects associated with less
urgent data in a different set of dbspaces: for example, less_urgent_dbs_1,
less_urgent_dbs_2, ... less_urgent_dbs_k. Lastly, you would place your remaining
data in a different set of dbspaces: for example, non_urgent_dbs_1,
non_urgent_dbs_2, .... non_urgent_dbs_r.
If you need to restore the server, you would first perform a cold restore of all
critical dbspaces and dbspaces containing urgent data, urgent_dbs_1 through
urgent_dbs_n. For example, assume that logical logs are distributed among two
dbspaces, logdbsp_1 and logdbsp_2, and the physical log is in rootdbs. The
critical dbspaces are therefore rootdbs, logdbsp_1, and logdbsp_2.
You would perform the initial cold restore by issuing the following ON-Bar
command:
onbar -r rootdbs logdbsp_1 logdbsp_2 urgent_dbs_1 ... urgent_dbs_2
You can bring the server online and all business-urgent data is available.
Finally, you can perform a warm restore for the rest of the server by issuing the
following command.
onbar -r
In a larger system with dozens of dbspaces, you can divide the warm restore
portion of the mixed restore into several warm restores, each restoring only a small
subset of the dbspaces remaining to be restored in the system.
The restore fails if insufficient space exists on the file system. The newly created
chunk files are cooked files and are owned by group informix on UNIX or group
Informix-Admin on Windows.
Restriction: ON-Bar does not recreate chunk files during a logical restore if the
logical logs contain chunk-creation records.
During initialization, ON-Bar saves the emergency boot file elsewhere and starts a
new, empty emergency boot file. Therefore, any backups that you performed before
reinitializing the database server are not recognized. You must use the copy of the
emergency boot file you saved before initialization to restore the previous database
server instance.
Tip: If you use symbolic links to chunk names, you might not need to rename
chunks; you only need to edit the symbolic name definitions.
Examples
The following table lists example values for two chunks that are used in the
examples in this section.
You can combine renaming chunks with existing devices and renaming chunks
with nonexistent devices in the same rename operation. This example shows how
to rename a single chunk to a nonexistent device name.
The following table lists example values for the chunks used in this example.
Storage space Old chunk path Old offset New chunk path New offset
sbspace1 /chunk3 0 /chunk3N 0
Prerequisites:
Important: Every chunk (including mirrors) must match exactly in size, location,
and offset on the source and target computers for the imported restore to complete.
10. Before you expire objects on the target computer and the storage manager
with the onsmsync utility, perform one of the following tasks. Otherwise,
onsmsync expires the incorrect objects.
v Manually edit the emergency boot file viz ixbar.servernum in the
$INFORMIXDIR/etc directory on the target computer. Replace the IBM
Informix server name that is used on the source computer with the IBM
Informix server name of the target computer
v Run the onsmsync -b command as user informix on the target computer to
regenerate the emergency boot file from the sysutils database only. The
regenerated emergency boot file reflects the server name of the target
computer.
Related reference:
There is more than one way to perform an imported restore. This example shows
the ISM catalog copy method. Another method, the bootstrap recovery method, is
described in the IBM Informix Storage Manager Administrator's Guide.
Prerequisites:
v A source machine and a target machine with the same configuration. However,
the server name and number can be different.
v A ROOTPATH that is the same on both machines.
v The target machine has the devices and links in place for the chunks and these
devices and links match those on the source machine.
v ISM is initialized on both computers.
v The paths to the device directories, volume names, and pool names are the same
on both machines.
v User root and user informix are ISM administrators on both machines.
In this example the directories for dbspace and log backups are:
<directory path>/dbspaces1
<directory path>/logfiles1
Restart a restore
onbar -RESTART
When you enable restartable restore, the logical restore is slower if many logical
logs are restored. However, you save time if the restore fails and you restart the
restore. Whether a restore is restartable does not affect the speed of the physical
restore.
The physical restore restarts at the storage space and level where the failure
occurred. If the restore failed while some, but not all, chunks of a storage space
were restored, all chunks of that storage space are restored. If storage spaces and
incremental backups are restored successfully before the failure, they are not
restored again.
The following figure shows how a restartable restore works when the restore failed
during a physical restore of dbspace2. The level-0, level-1, and level-2 backups of
rootdbs, and the level-0 and level-1 backups of dbspace1 and dbspace2 are
successfully restored. The database server fails while restoring the level-1 backup
of dbspace2. When you restart the restore, ON-Bar restores the level-2 backup of
dbspace 1, the level-1 and level-2 backups of dbspace2, and the logical logs.
If a restore fails during the logical phase and you restart the restore, ON-Bar
verifies that the storage spaces are restored, skips the physical restore, and restarts
the logical restore. The following figure shows a cold restore that failed while
restoring logical log LL-3. When you restart the cold logical restore, log replay
starts from the last restored checkpoint. In this example, the last checkpoint is in
logical log LL-2.
Important: If a failure occurs during a warm logical restore, restart the restore
from the beginning. If the database server is still running, run the onbar -r -l
command to complete the restore.
Cold restore failed during a logical restore of LL-3. The last checkpoint is in LL-2.
Related reference:
“onbar -r syntax: Restoring data” on page 6-3
“BAR_RETRY configuration parameter” on page 16-11
“RESTARTABLE_RESTORE configuration parameter” on page 16-19
“ON-Bar security” on page 4-11
You can save some failed restores even if restartable restore is turned off. For
example, if the restore fails because of a storage-manager or storage-device error,
you can fix the tape drive or storage-manager problem, remount a tape, and then
continue the restore.
The following table shows what results to expect when physical restore fails and
the value of the BAR_RETRY configuration parameter is > 1.
Table 6-6. Failed physical restore scenarios
RESTARTABLE_
Type of error RESTORE setting What to do when the physical restore fails?
Database server, ON or OFF ON-Bar tries each failed restore again. If the storage manager
ON-Bar, or failed, fix the storage-manager error.
storage-manager
error (database server If the tried restore fails, issue onbar -r spaces where spaces is the
is still running) list of storage spaces not yet restored. Use onstat -d to obtain the
list of storage spaces that need to be restored. ON-Bar restores the
level-0 backup of each storage space, then the level-1 and level-2
backups, if any.
The following table shows what results to expect when logical restore fails.
Table 6-7. Failed logical restore scenarios
RESTARTABLE_
Type of error RESTORE setting What to do when a logical restore fails?
Database server or ON Issue the onbar -RESTART command.
ON-Bar error in a cold
restore (database server is The logical restore restarts at the last checkpoint. If this
still running) restore fails, shut down and restart the database server to
initiate fast recovery of the logical logs. All logical logs not
restored are lost.
Database server or ON or OFF Issue the onbar -r -l command. The restore restarts at the
ON-Bar error (database failed logical log.
server is still running)
If onbar -r -l still fails, shut down and restart the database
server. The database server completes a fast recovery. All
logical logs that were not restored are lost.
Related reference:
“BAR_RETRY configuration parameter” on page 16-11
“RESTARTABLE_RESTORE configuration parameter” on page 16-19
ON-Bar does not move the data during the backup or physical restore. An external
backup allows you to copy disks that contain storage-space chunks without using
ON-Bar. When disks fail, replace them and use vendor software to restore the data,
then use ON-Bar for the logical restore. For more information, see “Data restored
in an external restore” on page 7-5.
The following are typical scenarios for external backup and restore:
v Availability with disk mirroring
If you use hardware disk mirroring, you can get your system online faster with
external backup and restore than with conventional ON-Bar commands.
v Cloning
You can use external backup and restore to clone an existing production system
for testing or migration without disturbing the production system.
During the blocking operation, users can access that database server in read-only
mode. Then you can physically back up or copy the data to another set of disks or
storage media by using operating-system or third-party tools. When you complete
the external backup, unblock the database server so that transactions can resume.
You should include all the chunk files in each storage space, administrative files,
such as onconfig, and the emergency boot file, in an external backup.
Important: To make tracking backups easier, you should back up all storage spaces
in each external backup.
Important: Because the external backup is outside the control of ON-Bar, you must
track these backups manually. For more information, see “Track an external
backup.”
onmode -c
block
unblock
The following table shows which items we recommend that you track in an
external backup. ON-Bar keeps a limited history of external restores.
Table 7-1. Items to track when you use external backup and restore
Items to track Examples
Full path names of each chunk file for each backed /work/dbspaces/rootdbs (UNIX)
up storage space
c:\work\dbspaces\rootdbs (Windows)
Object type Critical dbspaces, noncritical storage spaces
ins_copyid_hi and ins_copyid_lo Copy ID that the storage manager assigns to each backup object
Backup date and time The times that the database server was blocked and unblocked
Backup media Tape volume number or disk path name
Database server version The database server version from which the backup was taken.
Important: Because external backup is not done through ON-Bar, you must
ensure that you have a backup of the current logical log from the time when
you execute the onmode -c block command. Without a backup of this
logical-log file, the external backup is not restorable.
5. After you perform an external backup, back up the current log with the onbar
-b -l -c command.
If you lose a disk, or the whole system, you are now ready to perform an external
restore.
You can perform a logical restore from the logs backed up from the primary
instance. The backup obtained from the secondary server cannot be restored with
level-1 or level-2 backups.
Important: The external backup is not completed if the database instance contains
any of the following:
v Nonlogging smart large objects
v Regular blobspaces
v Nonlogging databases
v Raw tables
If an external backup is performed on an instance that contains any of the
previously mentioned items, then the backup is incomplete and cannot be used to
restore the primary server.
If the backup fails because the checkpoint from the primary has timed out, you can
use the BAR_CKPTSEC_TIMEOUT configuration parameter to increase the amount
of time, in seconds, that an RS secondary server should wait for a checkpoint to
arrive from the primary server while performing an external backup.
If the DELAY_APPLY configuration parameter is set, the logs that are required
for the restore process are not necessarily those logs that are currently active on
the primary server because some logs could already be archived.
Restriction: When you perform a cold external restore, ON-Bar does not first
attempt to salvage logical-log files from the database server because the external
backup has already copied over the logical-log data.
To salvage logical logs, perform onbar -l -s before you copy the external backup
and perform the external restore (onbar -r -e).
Rename chunks
You can rename chunks in an external cold restore by using the rename options
syntax for other restores. Use the following commands to specify new chunk
names during restore:
onbar -r -e -rename -f filename
or
onbar -r -e rename -p old_path -o old_offset-n new_path-o new_offset
onbar -r -e
(1) -p -O
Rename chunks -t time
-n last_log
-f filename
dbspace_list
-w
-t time
-n log
Notes:
1 See “onbar -b syntax: Backing up” on page 5-2
Related reference:
“onbar -r syntax: Restoring data” on page 6-3
Edit the script and backup a copy of the original file in case you need to revert to
it.
Important: Edit the script with caution and test your changes. Do not change the
cleanup code at the bottom of the script. Doing so might result in unexpected
behavior, for example, leftover temporary files during backup verification.
The script includes commands for Informix Storage Manager (ISM) and backs up
the ISM catalogs. If you are using a different storage manager, delete the
ISM-specific lines, and optionally, add commands for the storage manager that you
are using.
The installation program installs the default onbar shell script on UNIX and the
default onbar.bat batch script on Windows. If the default script differs from the
local script, the installation program backs up the local script and issues a message
to inform you that the local script was renamed. The naming convention of the
renamed file is onbar.date, where date is the date when the file was renamed. For
example, the file onbar.2012.05.15 was renamed on May 15, 2012.
You can update the default script by adding information to it from the renamed
script.
:backupcom
if "%1" == "-b" goto printboot
goto skip
:printboot
print %INFORMIXDIR%\etc\ixbar.???
REM Set the return code from onbar_d (this must be on the last line of the script)
:skip
%INFORMIXDIR%\bin\set_error %onbar_d_return%
:end
fi
done
if ! PHYS_ONLY; then # if logs were backed up, call another
migrate_logs # program to move them to tape
fi
:backupcom
if "%1" == "-b" goto m_log
if "%1" == "-l" goto m_log
goto skip
:m_log
migrate_log
REM Set the return code from onbar_d (this must be on the last line of the script)
:skip
%INFORMIXDIR%\bin\set_error %onbar_d_return%
:end
Depending on the command options you supply, the onsmsync utility can remove
the following items from the sysutils database and the emergency boot file:
v Backups that the storage manager has expired
v Old backups based on the age of backup
v Old backups based on the number of times they have been backed up
The onsmsync utility synchronizes the sysutils database, the storage manager, and
the emergency boot file as follows:
v Adds backup history to sysutils that is in the emergency boot file but is missing
from the sysutils database.
v Removes the records of restores, whole-system restores, fake backups, successful
and failed backups from the sysutils database.
v Expires old logical logs that are no longer needed.
v Regenerates the emergency boot file from the sysutils database.
ON-Bar always retains the latest level-0 backup for each storage space. It expires
all level-0 backups older than the specified time unless they are required to restore
from the oldest retained level-1 backup.
ON-Bar expires all level-1 backups older than the specified time unless they are
required to restore from the oldest retained level-2 backup.
ON-Bar retains a whole-system backup that starts before the specified retention
time and ends after the specified retention time.
onsmsync
-g generation -s -O -f filename -cf value
-t timestamp
-i interval
dbspace
-b
If the ixbar file has entries and the sysutils database was
rebuilt, but is empty because it does not contain data,
onsmsync -b recreates the sysutils data from the ixbar file.
Backups older than interval are not expired if they are needed
to restore from other backups after that interval. Use the ANSI
or GLS format for the interval: YYYY-MM or DD HH:MM:SS
-O Overrides internal error checks If used with the -t, -g, or -i option, expires all levels of a
and enforces expiration policy backup, even if some of them are needed to restore from a
backup that occurred after the expiration date. The -O option
does not affect logical-log expiration. See “Expire all backups”
on page 8-8.
-s Skips synchronizing expired The object expiration is based on other arguments if the -s
backups option is provided.
-t timestamp Expires all backups before a Retains backups that completed after the specified timestamp.
particular date and time Backups that occurred before the timestamp are not expired if
they are needed to restore from other backups that occurred
after the timestamp.
Tip: To control whether the sysutils database maintains a history for expired
backups and restores, use the BAR_HISTORY configuration parameter. For
information, see “BAR_HISTORY configuration parameter” on page 16-7.
The order of the commands does not matter except that the storage-space names or
file name must come last.
If you apply the -g option and the onsmsync utility list of objects contains only
logical logs and no space backups, the log backups are not expired. In this
situation, use the -t or -i option to expire logical log backups.
Examples
The following example expires backups that started before November 30, 2012:
onsmsync -t "2012-11-30 00:00:00""
onsmsync -g 2 -cf yes
Related tasks:
“Restoring when a backup is missing data” on page 5-17
“Performing a cold restore” on page 6-9
Related reference:
“ON-Bar script” on page 3-4
You must manually expire or delete the old backups from the storage manager.
Then, run onsmsync without any parameters.
Then use the onsmsync utility to recreate the backup and restore data in sysutils.
Restriction: If both the sysutils database and emergency boot file are missing, you
cannot regenerate them with onsmsync. Be sure to back up the emergency boot file
with your other operating-system files.
The following example expires all backups older than 18 months (written as 1 year
+ 6 months):
onsmsync -i "1-6"
In this example, the second timeline begins with a point-in-time restore to backup
1. The second timeline consists of backups 1, 5, 6, 7, and 8. The third timeline (in
bold) consists of backups 1, 5, and 9. The third timeline is considered the current
timeline because it contains the latest backup.
When you run the onsmsync utility to expire old backups, onsmsync removes the
old backups from the current timeline, and make sure that the current timeline is
restorable from the backup objects that are retained. All other backups that are not
in the current timeline are also expired but onsmsync does not make sure that the
other timelines are restorable from the objects retained.
The onsmsync utility applies expiration policies in the following order to make
sure that objects from current timeline are expired according to the specified
expiration policy and that the current timeline is restorable:
v Apply the expiration policy on all sets of backup objects.
v Unexpire backup objects that belong to the current timeline.
v Apply the expiration policy on the current timeline to ensure that the current
timeline is restorable.
At the same time, the expiration policy is applied to backups in other timelines.
For example, if you execute the onsmsync -g 2 command on the example in the
previous figure, backup 1 from the current timeline is expired, and backups 2, 3, 4,
6, and 7 from the first and second timelines are expired. Backups 1, 5, and 9 from
the current timeline are retained. Backup 8 is retained from other timelines.
Important: If you use the -O option with the -t, -i, or -g options, you might
accidentally delete critical backups, making restores impossible.
For example, the BAR_PERFORMANCE 1 setting displays the time spent transferring
data between the IBM Informix instance and the storage manager.
2013-06-03 15:38:02 8597 8595 Begin restore logical log 310 (Storage Manager
copy ID: 28206 0).
2013-06-03 15:38:03 8597 8595 Completed restore logical log 310.
2013-06-03 15:38:08 8597 8595 Completed logical restore.
2013-06-03 15:38:19 8597 8595 PERFORMANCE INFORMATION
TRANSFER RATES
------------------------------------------------------------------------------------------------------------------------
| OBJECT | XBSA API | SERVER API |
| NAME | xfer-kbytes xfer-time RATIO(kb/s) API-TIME | xfer-kbytes xfer-time RATIO(kb/s) API-TIME |
------------------------------------------------------------------------------------------------------------------------
| 309 | 62 0.479 129 1.078 | 62 0.019 3310 0.310 |
| 310 | 62 0.407 152 1.098 | 62 0.025 2522 0.025 |
| rootdbs | 5828 0.618 9436 1.864 | 5828 8.922 653 8.931 |
| datadbs01 | 62 0.488 127 1.768 | 62 0.004 17174 0.004 |
| datadbs02 | 62 0.306 203 1.568 | 62 0.008 8106 0.008 |
| datadbs03 | 62 0.304 204 1.574 | 62 0.007 8843 0.007 |
| datadbs04 | 62 0.306 202 1.563 | 62 0.007 8664 0.007 |
| datadbs05 | 62 0.315 197 1.585 | 62 0.007 8513 0.007 |
| datadbs06 | 62 0.310 200 1.583 | 62 0.002 25348 0.002 |
---------------- ----------------------------------- ... ---------------------------------------------------------------
| PID = 8597 | 14722 26.758 550 107.476 | 14756 10.678 1382 15.829 |
------------------------------------------------------------------------------------------------------------------------
2013-06-03 15:38:19 8597 8595 PERFORMANCE INFORMATION
PERFORMANCE CLOCKS
------------------------------------------------------------------------------------------------------------------------
| ITEM DESCIRPTION | TIME SPENT |
------------------------------------------------------------------------------------------------------------------------
| Time to Analyze ixbar file | 0.000 |
-------------------------------- ---------------------------------------------------------------------------------------
Figure 8-2. Sample transfer rate performance in the ON-Bar activity log
Figure 8-3. Sample processing rates, in microseconds, in the ON-Bar activity log
Related concepts:
“bar_act.log file: ON-Bar activity log” on page 3-4
Related reference:
“BAR_ACT_LOG configuration parameter” on page 16-3
“BAR_PERFORMANCE configuration parameter” on page 16-9
ON-Bar uses these tables for tracking backups and performing restores.
You can query these tables for backup and restore data to evaluate performance or
identify object instances for a restore.
ON-Bar writes a record to the bar_instance table for each successful backup.
ON-Bar might later use the information for a restore operation. For example, if you
specify a level-2 backup, ON-Bar uses this table to ensure that a level-1 backup
was done previously.
The schema of the bar_ixbar table is identical to the schema of the bar_syncdeltab
table, except for its primary key.
Table 9-3. bar_ixbar table columns
Column name Type Explanation
ixb_sm_id INTEGER Storage-manager instance ID. Created from BAR_SM
in $ONCONFIG or %ONCONFIG%.
ixb_copyid_hi INTEGER The high bits of the instance copy identifier.
Combined with ixb_copyid_lo, it is a unique value
that the storage manager assigns to link the ON-Bar
object identifier with the storage-manager object
identifier.
ixb_copyid_lo INTEGER The low bits of the instance copy identifier.
Combined with ixb_copyid_hi, it is a unique value
that the storage manager assigns to link the ON-Bar
object identifier with the storage-manager object
identifier.
ixb_aid INTEGER Action identifier, Identifies the successful action that
created this instance of the backup object.
ixb_old INTEGER Object identifier. Identifies the affected object.
ixb_time INTEGER Time stamp (real clock time). The database server
uses this value when it creates the next-level
backup. Value represents the number of seconds
since midnight, January 1, 1970, Greenwich mean
time.
ixb_prevtime INTEGER Time stamp (real clock time). This value specifies the
time stamp of the previous object. Value represents
the number of seconds since midnight, January 1,
1970 Greenwich mean time.
ixb_rsam_time INTEGER The backup checkpoint time stamp. Not a clock
time. The database server uses this value when it
creates the next level backup.
ixb_act_start datetime year to The date and time when the action began.
second
Related reference:
“The bar_syncdeltab table” on page 9-5
The following figure maps the ON-Bar tables on IBM Informix. In this figure, the
gray lines show the relations between tables. The arrows show that the ins_req_aid
value must be a valid ins_aid value.
A message in the ON-Bar activity log file, bar_act.log, has the following format:
The following table describes each field in the message. No error message numbers
appear in the ON-Bar activity log.
Table 10-1. ON-Bar message format
Message field Description
timestamp Date and time when ON-Bar writes the message.
process_id The number that the operating system uses to identify this instance of
ON-Bar.
parent_process_id The number that the operating system uses to identify the process that
executed this instance of ON-Bar.
message The ON-Bar message text.
The following example illustrates a typical entry in the ON-Bar activity log:
1999-08-18 10:09:59 773 772 Completed logical restore.
If a storage manager process hangs, the timestamp for the process in the ON-Bar
activity log is inaccurate. An asterisk symbol is appended to the timestamp and the
message indicates how long the storage manager process hung. The following
example shows that the storage manager process hung for two minutes starting at
10:27. At 10:29, the storage manager completed the backup.
2013-02-26 10:29:12 13410 25695 Completed level 0 backup dbspace1 (Storage Manager
copy ID: 1509564809 0).
Related reference:
“onbar -m syntax: Monitoring recent ON-Bar activity” on page 5-9
Message numbers
The ON-Bar message numbers range from -43000 to -43421.
The following table lists the ON-Bar message groups. Because message numbers
do not display in the activity log, the best way to find information about ON-Bar
messages is to search for the message text in the error messages file, which is in
the subdirectory for your locale under the $INFORMIXDIR/msg directory.
The following table shows the ON-Bar return codes for all IBM Informix database
servers. These return codes are accompanied by messages in the ON-Bar activity
log. For details about an error, review the activity log before you call Technical
Support.
Table 10-2. Common ON-Bar return codes
Decimal value ON-Bar return code description
2 through 34 These return codes are produced by XBSA. For more information, consult your storage-manager
documentation and log files.
100 ON-Bar cannot find something in sysutils, the emergency boot file, or storage-manager catalogs
that it needs for processing.
Check the ON-Bar activity log for messages that say what could not be found and try to resolve
that problem. If the problem recurs, contact Technical Support.
ON-Bar does not support ADSM running in generate-password mode. For information about
changing the ADSM security configuration, refer to your ADSM manual.
115 A critical dbspace is not in the set of dbspaces being cold-restored.
116 The onsmsync utility is already running.
117 The information contained in the sysutils database and the emergency boot file are inconsistent.
118 An error trying to commit a backup object to the storage manager.
120 The transport buffer size has changed since this object was last backed up. This object cannot be
restored. Set the transport-buffer size to its original value and try the restore again.
121 ON-Bar was unable to determine the list of dbspaces.
122 Deadlock detected.
The ON-Bar command is contending with another process. Try the ON-Bar command again.
123 The root dbspace was not in the cold restore.
You cannot perform a cold restore without restoring the root dbspace. To resolve the problem, try
one of the following procedures:
v Bring the database server to quiescent or online mode and restore just the storage spaces that
need to be restored.
v If the database server is offline, issue the onbar -r command to restore all the storage spaces.
v Make sure that the root dbspace and other critical dbspaces are listed on the command line or
in the -f filename.
124 The buffer had an incomplete page during the backup.
Check the ON-Bar activity log for descriptions of the problem and the emergency boot file for
corruption such as non-ASCII characters or lines with varying numbers of columns. If the source
of the problem is not obvious, contact Technical Support.
127 Could not write to the emergency boot file.
Often, an operating-system error message accompanies this problem. Check the permissions on the
following files and directories:
v $INFORMIXDIR/etc on UNIX or %INFORMIXDIR%\etc on Windows
v The emergency boot file
128 Data is missing in the object description.
Run onsmsync to synchronize the sysutils database, emergency boot file, and storage-manager
catalogs. For assistance, contact Technical Support.
The database server probably failed during the backup or restore. Run the onstat - command to
check the database server status and then:
v If the operation was a cold restore, restart it.
v If the operation was a backup or warm restore, restart the database server and try the backup
or warm restore again.
131 A failure occurred in the interface between ON-Bar and the database server.
Verify that you are using the correct XBSA for the storage manager. For information, consult your
storage-manager manual.
133 Failed to load the XBSA library functions.
Verify that you are using the correct XBSA for the storage manager. Ensure that the
BAR_BSALIB_PATH value in the onconfig file points to the correct location of the XBSA shared
library. For information, consult your storage-manager manual.
134 User wants to restore a logical-log file that is too early.
You probably tried a point-in-log restore (onbar -r -l -n) after performing a separate physical
restore. The specified logical log is too old to match the backups used in the physical restore.
Perform either of the following steps:
v Rerun the physical restore from an older set of physical backups.
v Specify a later logical log in the -n option when you rerun the point-in-log restore. To find the
earliest logical log that you can use, look at the emergency boot file. For assistance, contact
Technical Support.
136 ON-Bar cannot warm restore the critical dbspaces.
Verify that you are using the correct XBSA for the storage manager. Also check the bar_act.log
for XBSA error messages. For information, consult your storage-manager manual.
139 Either the XBSA version is missing from the sm_versions file or the incorrect XBSA version is in
the sm_versions file.
Insert the correct XBSA version into the sm_versions file. For more information, consult your
storage-manager manual.
140 A fake backup failed.
Try the fake backup with the onbar -b -F command again. Only IBM Informix supports fake
backups. If the fake backup fails again, contact Technical Support.
141 ON-Bar received an operating-system signal. Most likely, the user entered the Ctrl-C command to
stop an ON-Bar process.
Fix the cause of the interruption and then try the ON-Bar command again.
Verify that the named file exists and that the permissions are correct. Check the ON-Bar activity
log for an operating-system error message.
143 ON-Bar was unable to create a child process.
If BAR_MAX_BACKUP is not 0, ON-Bar could not create child processes to perform the parallel
backup or restore. The operating system probably ran out of resources. Either not enough memory
is available to start a new process or no empty slot exists in the process table.
Check the operating-system logs, the ON-Bar activity log, or the console.
144 The log backup was stopped because one or more blobspaces were down.
Attempt to restore the blobspace. If the restore fails, try the log backup with the onbar -l -O
command again. Executing this command might make the blobspace unrestorable.
145 ON-Bar was unable to acquire more memory space.
Wait for system resources to free up and try the ON-Bar command again.
146 ON-Bar was unable to connect to the database server.
The network or the database server might be down. For assistance, contact Technical Support.
147 ON-Bar was unable to discover any storage spaces or logical logs to back up or restore.
For example, if you specify a point-in-time restore but use a datetime value from before the first
standard backup, ON-Bar cannot build a list of storage spaces to restore. This return code also
displays if you specify a whole-system restore without having performed a whole-system backup.
Verify that the database server and the storage spaces are in the correct state for the backup or
restore request. Contact Technical Support.
148 An internal SQL error occurred.
Provide Technical Support with the information from the ON-Bar activity log.
149 Either you entered the wrong ON-Bar syntax on the command line or entered an invalid or
incorrect datetime value for your GLS environment.
Check the command that you tried against the usage message in the ON-Bar activity log. If that
does not help, then try the command with quotes around the datetime value again. If your
database locale is not English, use the GL_DATE or GL_DATETIME environment variables to set the
date and time format.
150 Error collecting data from the onconfig file.
Check the permissions, format, and values in the onconfig file. Check that the ONCONFIG
environment variable is set correctly.
Either you attempted an operation that is not compatible with the database server mode or
ON-Bar is unable to determine the database server state. For example, you cannot do a physical
backup with the database server in recovery mode.
Check the error message in the ON-Bar activity log. If an ASF error occurred, the following
message displays in the ON-Bar activity log:
Fatal error initializing ASF; asfcode = code
To determine the cause of the ASF error, refer to the ASF error code in this message and repeat the
backup or restore command. If an ASF error did not occur, change the database server state and
repeat the backup or restore command.
152 ON-Bar cannot back up the logical logs.
The logical logs are not backed up for either of the following reasons:
v If another log backup is currently running.
v If you perform a logical-log backup with the LTAPEDEV parameter set to /dev/null (UNIX) or
NUL (Windows).
You receive this return code when no log backups can be done.
You must be user root or informix or a member of the bargroup group on UNIX or a member of
the Informix-Admin group on Windows to execute ON-Bar commands.
155 The INFORMIXSERVER environment variable is not set.
Set the INFORMIXSERVER environment variable to the correct database server name.
156 Backup or restore was not performed because the LTAPEDEV parameter value is not valid.
If LTAPEDEV is not set or /dev/null on UNIX, or if it is NUL on Windows, the logical logs are not
backed up, and ON-Bar returns warning 152.
157 Error attempting to set the INFORMIXSHMBASE environment variable to -1.
ON-Bar could not set INFORMIXSHMBASE to -1. For assistance, contact either the system
administrator or Technical Support.
158 An internal ON-Bar error occurred.
To determine what went wrong with the external restore, look at the bar_act.log and the
online.log files. Ensure that you already performed the manual part of the external restore before
you try the onbar-r -e command again to complete the external restore. If that does not work, try
the external restore from a different external backup.
Verify that RESTARTABLE_RESTORE is set to ON and try the original restore again. For more
information, check the ON-Bar activity log and database server message logs.
162 The ON-Bar log file cannot be a symbolic link.
Remove the symbolic link or change the onconfig file so that the ON-Bar parameters
BAR_DEBUG_LOG or BAR_ACT_LOG point to non-symbolic linked files.
163 The ON-Bar log file must be owned by user informix.
Change the ownership of the log file to be owned by user informix or change the BAR_ACT_LOG
or BAR_DEBUG_LOG values in the onconfig file to point to different log files.
164 Unable to open file.
The file or its directory permissions prevent it from being created or opened. Verify the
permissions on the file and its directory.
177 An online dbspace was restored. This return code notifies the user that the -O option overrode the
internal checks in ON-Bar.
Examine the data in the blobspace to determine which simple large objects you need to recreate.
These blobspaces might not be restorable. For assistance, contact Technical Support.
179 ON-Bar created the chunk needed to restore the dbspace. This return code notifies the user that
the -O option overrode the internal checks in ON-Bar.
Create the chunk file manually. Try the restore without the -O option again.
181 ON-Bar expired an object that was needed for a backup or restore.
The onsmsync utility expired an object that might be needed for a restore. You probably specified
onsmsync with the -O option. If you used the -O option by mistake, contact Technical Support to
recover the object from the storage manager.
183 ON-Bar could not obtain the logical-log unique ID from the storage manager.
The backup of the specified logical log is missing. Query your storage manager to determine if the
backup of the specified logical-log file exists and if it is restorable.
247 On UNIX, look in /tmp/bar_act.log and the file that the BAR_ACT_LOG parameter points to for
clues. (The onbar-merger writes to /tmp/bar_act.log until it has enough information to read the
onconfig file.) Resolve the problems that the bar_act.log describes and try the cold restore again.
If the cold restore still fails, contact Technical Support.
252 For assistance, contact Technical Support.
You can also set the IFX_BAR_USE_DEDUP environment variable to optimize the
backup images for deduplication devices.
Related reference:
“IFX_BAR_USE_DEDUP environment variable” on page 16-14
“Comparison of the ON-Bar and ontape utilities” on page 1-8
The onconfig file is located in the $INFORMIXDIR/etc directory. You specify that file
in the ONCONFIG environment variable. For a description of the ONCONFIG
environment variable and instructions on how to set it, see the IBM Informix Guide
to SQL: Reference.
Prerequisite: The data must have previously been transformed with the
BACKUP_FILTER parameter.
The following list shows backup tape devices and their associated tape parameters.
TAPEDEV
The absolute path name of the tape device or directory file system that is used
for storage-space backups. Specify the destination where ontape writes storage
space data during an archive and the source from which ontape reads data
during a restore.
To configure ontape to use stdio, set TAPEDEV to STDIO.
When backing up to or restoring from a cloud environment, use the following
syntax for the TAPEDEV configuration parameter:
TAPEDEV ’local_path, keep=option, cloud=cloud_vendor, url=url’
v local_path is the complete path name of the directory where storage spaces
backup objects are stored temporarily.
v option can be set to yes or no. If keep is set to yes, the ontape utility retains
the backup objects in the local directory. If keep is set to no, the backup
objects are deleted after they are transferred to or from the cloud storage
location.
v cloud_vendor is the name of the cloud storage vendor.
v url is the cloud storage location where the storage space backup data is
stored persistently.
TAPEBLK
The block size of the tapes used for storage-space backups, in kilobytes.
TAPESIZE
The size of the tapes used for storage-space backups, in kilobytes. The value
can be 0 - 2,097,151.
The following list shows the logical-log tape devices and their associated tape
parameters.
LTAPEDEV
The logical-log tape device or a directory of a file system.
When backing up to or restoring from a cloud environment, use the following
syntax for the LTAPEDEV configuration parameter:
LTAPEDEV ’local_path, keep=option, cloud=cloud_vendor, url=url’
v local_path is the complete path name of the directory where log backup
objects are stored temporarily.
v option can be set to yes or no. If keep is set to yes, the ontape utility retains
the backup objects in the local directory. If keep is set to no, the backup
objects are deleted after they are transferred to or from the cloud storage
location.
v cloud_vendor is the name of the cloud storage vendor.
v url is the cloud storage location where the log backup data is stored
persistently.
LTAPEBLK
The block size of tapes used for logical-log backups, in kilobytes.
The following topics contain information about how to set the tape-device,
tape-block-size, and tape-size parameters for both storage-space and logical-log
backups.
Related tasks:
“Back up to Amazon Simple Storage Service” on page 12-9
If you specify the same device for the LTAPEDEV and TAPEDEV, the logical log
can fill, which causes the database server to stop processing during a backup.
When this happens, you have two options.
v Stop the backup to free the tape device and back up the logical-log files.
v Leave normal processing suspended until the backup completes.
When only one tape device exists and you want to create backups while the
database server is online, take the following precautions:
v Configure the database server with a large amount of logical-log space through a
combination of many or large logical-log files. (See your IBM Informix
Administrator's Guide.)
v Store all explicitly created temporary tables in a dedicated dbspace and then
drop the dbspace before backing up.
v Create the backup when low database activity occurs.
v Free as many logical-log files as possible before you begin the backup.
The logical log can fill up before the backup completes. The backup synchronizes
with a checkpoint. A backup might wait for a checkpoint to synchronize activity,
but the checkpoint cannot occur until all virtual processors exit critical sections.
When database server processing suspends because of a full logical-log file, the
Chapter 11. Configure ontape 11-3
virtual processors cannot exit their critical sections and a deadlock results.
When you set the LTAPEDEV configuration parameter, as the following example
shows, you can switch to a different device without changing the LTAPEDEV
parameter:
LTAPEDEV /dbfiles/logtape
You only need to change the symbolic link, as the following example shows:
ln -s /usr/backups /dbfiles/logtape
A user with one tape device could redirect a logical-log back up to a disk file while
using the tape device for a backup.
To specify a file system directory, set the LTAPEDEV and TAPEDEV configuration
parameters to the absolute path name for the directory.
When ontape repeats an archive operation, it renames the existing files so that old
files are not rewritten. A timestamp is added to the file name, which provides a
way for related storage space or logical log files to be organized together.
To learn about the file naming schema, see “Rename existing files” on page 12-6.
The remote device and the database server computer must have a trusted
relationship so that the rsh or the rlogin utility can connect from the database
server computer to the remote device computer without asking for password. You
can establish a trusted relationship by configuring the /etc/hosts.equiv file, the
~/.rhosts file, or any equivalent mechanism for your system on the remote device
computer. If you want to use a different utility to handle the remote session than
the default utility used by your platform, you can set the DBREMOTECMD environment
variable to the specific utility that you want to use.
To specify a tape device on another host computer, use the following syntax to set
the TAPEDEV or LTAPEDEV configuration parameter:
host_machine_name:tape_device_pathname
The following example specifies a tape device on the host computer kyoto:
kyoto:/dev/rmt01
When you specify /dev/null as a backup tape device, you can avoid the overhead
of a level-0 backup that is required after some operations, such as changing the
logging status of a database. Obviously, you cannot restore storage spaces from a
backup to /dev/null.
When you specify the tape device as /dev/null, block size and tape size are
ignored. If you set the LTAPEDEV configuration parameter either to or from
/dev/null, you must restart the database server for the new setting to take effect.
When you set the tape parameter to /dev/null, the corresponding block size is
ignored.
The ontape utility does not check the tape device when you specify the block size.
Verify that the tape device can read the block size that you specified. If not, you
cannot restore the tape.
To write or read the tape to the end of the device, set TAPESIZE and LTAPESIZE
to 0. You cannot use this option for remote devices.
When you specify the tape device as /dev/null, the corresponding tape size is
ignored.
When you perform a continuous logical-log backup to a remote device, the amount
of data written to the tape is the smaller of LTAPESIZE and the following formula:
(sum of space occupied by all logical-log files on disk) -
(largest logical-log file)
The I/O to the remote device completes and the database server frees the
logical-log files before a log-full condition occurs.
You can change the values of parameters for ontape while the database server is
online.
The change takes effect immediately. However, if you set either the TAPEDEV
parameter or the LTAPEDEV parameter to /dev/null, you must restart the
database server.
Related reference:
“LTAPEBLK configuration parameter” on page 16-16
“LTAPEDEV configuration parameter” on page 16-16
“LTAPESIZE configuration parameter” on page 16-18
“TAPEBLK configuration parameter” on page 16-20
“TAPEDEV configuration parameter” on page 16-21
“TAPESIZE configuration parameter” on page 16-23
Start ontape
When you need more than one tape during a backup, the ontape utility prompts
for each additional tape.
Restriction: Do not start the ontape utility in background mode (that is, with the
UNIX & operator on the command line). You could also need to provide input
from the terminal or window. When you execute ontape in background mode, you
can miss prompts and delay an operation.
The ontape utility does not include default values for user interaction, nor does it
support attempts to retry. When ontape expects a yes-or-no response, it assumes
that any response not recognized as a “yes” is “no”.
Examples
The following command changes the logging mode of a database named stores7 to
unbuffered logging:
ontape -s -L 0 -U stores7
Create a backup
These topics explain how to plan for and create backups of your database server
data.
For information about scheduling backups, see “Plan a recovery strategy” on page
2-1.
Tip: Establish a backup schedule that keeps level-1 and level-2 backups small.
Schedule frequent level-0 backups to avoid restoring large level-1 and level-2
backups or many logical-log backups.
Level-0 backup
When a fire or flood, for example, completely destroys a computer, you
need a level-0 backup to completely restore database server data on the
replacement computer. For online backups, the data on the backup tape
reflects the contents of the storage spaces at the time the level-0 backup
began. (The time the backup started could reflect the last checkpoint before
the backup started.)
A level-0 backup can consume lots of time because ontape must write all
the pages to tape.
Level-1 backup
A level-1 backup usually takes less time than a level-0 backup because you
copy only part of the database server data to the backup tape.
Level-2 backup
A level-2 backup after a level-1 backup usually takes less time than another
level-1 backup because only the changes made after the last level-1 backup
(instead of the last level-0) get copied to the backup tape.
Perform a level-0 backup after you make the following administrative changes:
v Changing the TAPEDEV or LTAPEDEV configuration parameter from /dev/null
v Adding logging to a database
v Adding a dbspace, blobspace, or sbspace before you can restore it with anything
less than a full-system restore
v Starting mirroring for a dbspace that contains logical-log files
v Dropping a logical-log file
v Moving one or more logical-log files
v Changing the size or location of the physical log and after you set up shared
memory
v Dropping a chunk before you can reuse the dbspace that contains that chunk
v Renaming a chunk during a cold restore
Consider waiting to make these changes until your next regularly scheduled
level-0 backup.
Online backup
You can use an online backup when you want your database server accessible
while you create the backup.
Some minor inconveniences can occur during online backups. An online backup
can slow checkpoint activity, and that can contribute to a loss in performance.
However, this decline in performance is far less costly than the time that you lose
when users were denied access to the database server during a backup.
During an online backup, allocation of some disk pages in storage spaces can
temporarily freeze. Disk-page allocation is blocked for one chunk at a time until
you back up the used pages in the chunk.
Quiescent backup
You create a quiescent backup while the database server is quiescent. Use quiescent
backups when you want to eliminate partial transactions in a backup.
Do not use quiescent backups when users need continuous access to the databases.
Back up to tape
When you back up to tape, you must ensure that an operator is available and that
you have sufficient media.
Each backup begins with its first tape reel numbered 1. You number each
additional tape reel consecutively thereafter. You number a five-tape backup 1
through 5. (Of course, it is possible that you could not know that it is a five-tape
backup until it is finished.)
When you back up to standard output, ontape does not prompt for user
interaction. Error and information messages are written to stderr instead of being
directed to standard output.
You can simultaneously back up and restore a database server to clone it or set up
High-Availability Data Replication. For more information, see “Simultaneous
backup and restore by using standard I/O” on page 13-14.
Related reference:
“Restore from standard input” on page 13-13
The person who runs the backup must have write permission to the directory. The
directory must have enough disk space to hold the backed-up data. You can use
operating system utilities to compress the data after it is backed up.
Tip: When you back up to a directory file system, specify the -d option to turn off
ontape interactive prompts.
When ontape repeats an archive operation, it renames the existing files so that old
files are not rewritten. A timestamp is added to the file name, which provides a
way for related storage space or logical log files to be organized together.
Renaming conventions:
v Storage-space archive files
The archive checkpoint time is added, and has the format
servername_YYYYMMDD_hhmmss_archive-level.
v Logical log backup files
The backup time is added, and has the format servername_YYYYMMDD_hhmmss.
When restoring from a file system directory, ontape requires that storage-space
archive and logical-log backup files be named as specified by the TAPEDEV and
LTAPEDEV parameters. If files have been renamed, including by ontape because of
repeated archives and backups, files must be manually renamed to their original
file names.
If you are using TAPE devices, do not store more than one backup on the same
tape. The tape devices must be of the rewindable type. Begin every backup with a
different tape. (Often, a backup spans more than one tape.)
Syntax
Create a backup
ontape
-v
-s
-L 0 -F -t
1 tape_device
2 STDIO
-L 0 -B database
-U
-A
-N
-N database
-d
The ontape utility backs up the storage spaces in the following order: root
dbspaces, blobspaces, sbspaces, and dbspaces.
Related reference:
“Change database logging status” on page 12-1
You can use the -L option to specify the level of the backup as part of the
command, as the following example shows: ontape -s -L 0
Use the -d option to avoid interactive prompts when you are backing up to or
restoring from a directory: ontape -s -L 0 -d
When you do not specify the backup level on the command line, ontape prompts
you to enter it. The following figure illustrates a simple ontape backup session.
ontape -s
Please enter the level of archive to be performed (0, 1, or 2) 0
Program over.
The following example shows how to create a level-0 archive of all storage spaces
to standard output, which is diverted to a file named level_0_archive in the
directory /home:
ontape -s -L 0 >/home/level_0_archive -t STDIO
The following example assumes TAPEDEV STDIO in onconfig and creates a level-1
archive to standard output , which is diverted to a pipe:
ontape -v -s -L 1|compress -c >/home/compressed/level_1_archive
The compress system utility reads from the pipe as input, compresses the data,
and writes the data to the file level_1_archive in the /home/compressed directory.
The ontape information messages are sent to stderr.
The following steps show how to back up data to the Amazon Simple Storage
Service (S3) System and restore from it by using ontape backup and restore utility.
In this context, cloud storage refers to an online storage service over the Internet. If
you choose to back up to cloud storage, you do not need to provide tapes. Instead,
you back up the data to a virtual device, most likely located on the Internet.
1. Configure the online storage device.
a. Using a web browser, navigate to the Amazon S3 website and log on.
b. Obtain an access key ID and a secret access key.
c. Store the access credentials in a file. Set the permissions on the file to allow
access only to user executing the ontape utility.
v On UNIX systems, store the values in the file: $INFORMIXDIR/etc/
ifxbkpcloud.credentials
v On Windows systems, store the values in: %INFORMIXDIR%\etc\
ifxbkpcloud.credentials
The file must have the following format:
secretKey=secret_access_key
accessKey=access_key_ID
d. Use the ifxbkpcloud.jar utility to create and name a storage device in the
region where you intend to store Informix data. Amazon uses the term
bucket to describe the container for backup data. The storage device name
you choose has the same restrictions as those for the bucket name in
Amazon S3 and must be unique.
For example, the following command creates a storage device named
mytapedevice at a US Standard region on Amazon S3. Run the command
from the $INFORMIXDIR/bin directory on UNIX systems, or from
%INFORMIXDIR%\bin on Windows systems.
java -jar ifxbkpcloud.jar CREATE_DEVICE amazon mytapedevice US_Standard
2. Set the TAPEDEV and LTAPEDEV configuration parameters in the onconfig file
to point to the cloud storage location. For example:
TAPEDEV ’/opt/IBM/informix/tapedev_dir, keep = yes, cloud = amazon,
url = https://mytapedevice.s3.amazonaws.com’
LTAPEDEV ’/opt/IBM/informix/ltapedev_dir, keep = yes, cloud = amazon,
url = https://mylogdevice.s3.amazonaws.com’
3. Back up data to the online storage device by using the ontape utility.
ontape -s -L 0
You can restore data from the cloud storage by using the following command:
ontape -r
You should use https secure data transmission when transferring data to cloud
storage. You should encrypt data before transferring data to a cloud image. To
encrypt data, use the BACKUP_FILTER and RESTORE_FILTER configuration
parameters to call an external encryption program. The archecker utility does
not support table-level restore of data from cloud storage.
Related reference:
“Tape and tape device parameters for ontape” on page 11-2
“Set the tape-device parameters” on page 11-3
Data space backup files are saved by using the following format:
hostname_servernum_Larchive_level
Log backup file names are saved by using the following format:
hostname_servernum_lognnnnnnnnnn
If the object exists at the cloud storage location, the file is renamed to avoid
overwriting old object. Renaming the file adds a timestamp to the object name.
Data space backup files are saved by using the following format:
hostname_servernum_YYYYMMDD_hhmmss_Larchive_level
Log backup file names are saved by using the following format:
hostname_servernum_lognnnnnnnnnn_YYYYMMDD_hhmmss
Related tasks:
“Back up to Amazon Simple Storage Service” on page 12-9
When you can use two tape devices with the database server, log in as the owner
of the database server: user informix or root for a standard installation, or the
owner of the non-root installation.
Verify that LTAPEDEV and TAPEDEV specify different path names that correspond
to separate tape devices. When they do, back up the logical-log files. See “Create a
backup” on page 12-2.
When LTAPEDEV and TAPEDEV are identical, assign a different value to the
logical-log tape device (LTAPEDEV) and initiate a logical-log-file backup.
Otherwise, your options are to either leave normal database server processing
suspended until the backup completes or cancel the backup.
When you create a backup with the only available tape device, you cannot back up
any logical-log files until you complete the backup. When the logical-log files fill
during the backup, normal database server processing halts. You can either stop
the backup (by using Ctrl-C only) to free the tape device and back up the logical
logs to continue processing, or leave normal processing suspended until the
backup completes.
You can take steps to prevent this situation. The section “Start an automatic
logical-log backup” on page 12-14 describes these steps.
Execute the oncheck -pr command to display reserved-page information for the
root dbspace. The last pair of reserved pages contains the following information for
the most recent backup:
v Backup level (0, 1, or 2)
v Effective date and time of the backup
v Time stamp describing when the backup began (expressed as a decimal)
v ID number of the logical log that was current when the backup began
v Physical location in the logical log of the checkpoint record (that was written
when the backup began)
The effective date and time of the backup equals the date and time of the
checkpoint that this backup took as its starting point. This date and time could
differ markedly from the time when the backup process was started.
For example, when no one accessed the database server after Tuesday at 7 P.M.,
and you create a backup Wednesday morning, the effective date and time for that
backup is Tuesday night, the time of the last checkpoint. In other words, when
In addition to backing up logical-log files, you can use ontape to switch to the next
log file, move logical-log files to other dbspaces, or change the size of the logical
log. Instructions for those tasks appear in your IBM Informix Administrator's Guide.
For more information about these issues, see “Logical-log backup” on page 1-2.
Use blobspace TEXT and BYTE data types and logical-log files
You must keep in mind the following two points when you use TEXT and BYTE
data types in a database that uses transaction logging:
v To ensure timely reuse of blobpages, back up logical-log files. When users delete
TEXT or BYTE values in blobspaces, the blobpages do not become freed for
reuse until you free the log file that contains the delete records. To free the log
file, you must back it up.
v When you must back up an unavailable blobspace, ontape skips it and makes it
impossible to recover the TEXT or BYTE values when it becomes necessary.
(However, blobpages from deleted TEXT or BYTE values do become free when
the blobspace becomes available even though the TEXT or BYTE values were not
backed up.)
In addition, regardless of whether the database uses transaction logging, when you
create a blobspace or add a chunk to a blobspace, the blobspace or new chunk is
not available for use until the logical-log file that records the event is not the
current logical-log file. For information about switching logical-log files, see your
IBM Informix Administrator's Guide.
Fast recovery and rolling back transactions are not impaired when you use
/dev/null as your log-file backup device. For a description of fast recovery, see
your IBM Informix Administrator's Guide. For information about rolling back
transactions, see the ROLLBACK WORK statement in the IBM Informix Guide to
SQL: Syntax.
ontape -a
The -a option backs up all full logical-log files and prompts you with an option to
switch the logical-log files and back up the formerly current log.
When the tape mounted on LTAPEDEV becomes full before the end of the
logical-log file, ontape prompts you to mount a new tape.
When you press the Interrupt key while a backup occurs, the database server
finishes the backup and then returns control to you. Any other full logical-log files
receive a used status.
When you start a continuous backup, the database server automatically backs up
each logical-log file as it becomes full. When you perform continuous logical-log
file backups, the database server protects you against ever losing more than a
partial logical-log file, even in the worst case media failure when a chunk that
contains logical-log files fails.
To start a continuous backup of the logical-log files, use the ontape -c command.
The -c option initiates continuous backup of logical-log files. The database server
backs up each logical-log file as it becomes full. Continuous backup does not back
up the current logical-log file. The database server can operate in online mode
when you start continuous backups.
When you press the Interrupt key while the database server backs up a logical-log
file to a local device, all logs that were backed up before the interrupt are captured
on the tape and are marked as backed up by the database server.
When you press the Interrupt key while the database server waits for a logical-log
file to fill (and thus is not backing up any logical-log files), all logs that were
backed up before the interrupt reside on the tape and are marked as backed up by
the database server.
When you press the Interrupt key while the database server performs a continuous
backup to a remote device, any logical-log files that were backed up during this
operation can or cannot reside on the tape, and are not marked as backed up by
the database server (a good reason why you should not do continuous remote
backups).
After you stop continuous logging, you must start a new tape for subsequent log
backup operations.
You must explicitly request logical-log backups (by using ontape -a) until you
restart continuous logging.
Before you start restoring data, you must understand the concepts in “Restore
systems” on page 1-4. As explained in that section, a complete recovery of
database server data generally consists of a physical restore and a logical restore.
Full-system restore
When your database server goes offline because of a disk failure or corrupted data,
it means that a critical dbspace was damaged. The following list shows critical
dbspaces:
v The root dbspace
v The dbspace that contains the physical log
v A dbspace that contains logical-log files
When you need to restore any critical dbspace, you must perform a full system
restore to restore all the data that your database server manages. You must start a
full-system restore with a cold restore. See “Cold, warm, or mixed restores.”
When you do not need to restore a critical dbspace, you can restore only those
storage spaces that contain a damaged chunk or chunks. When a media failure
occurs in one chunk of a storage space that spans multiple chunks, all active
transactions for that storage space must terminate before the database server can
restore it. You can start a restore operation before the database server finishes the
transactions, but the restore becomes delayed until the database server verifies that
you finished all transactions that were active at the time of the failure.
The database server is offline when you begin a cold restore but it goes into
recovery mode after it restores the reserved pages. From that point on it stays in
recovery mode until either a logical restore finishes (after which it works in
quiescent mode) or you use the onmode utility to shift it to another mode.
You can rename chunks by specifying new chunks paths and offsets during a cold
restore. This option is useful if you need to restore storage spaces to a different
disk from the one on which the backup was made. You can rename any type of
chunk, including critical chunks and mirror chunks. For more information, see
“Rename chunks during a restore” on page 13-10. You can also rename chunks for
an external cold restore; see “Rename chunks” on page 14-5 for more information.
A cold restore can be performed after a dbspace has been renamed and a level-0
backup or a backup of the rootdbs and renamed dbspace is performed.
Warm restores
A warm restore restores noncritical storage spaces while the database server is in
online or quiescent mode. It consists of one or more physical restore operations
(when you restore multiple storage spaces concurrently), a logical-log backup, and
a logical restore.
During a warm restore, the database server replays backed-up logical-log files for
the storage spaces that you restore. To avoid overwriting the current logical log,
the database server writes the logical-log files that you designate for replay to
temporary space. Therefore, a warm restore requires enough temporary space to
hold the logical log or the number of log files being replayed, whichever is smaller.
For information about how the database server looks for temporary space, see the
discussion of DBSPACETEMP in the IBM Informix Administrator's Guide.
Important: Make sure that enough temporary space exists for the logical-log
portion of the warm restore; the maximum amount of temporary space that the
database server needs equals the size of all the logical-log files.
A warm restore can be performed after a dbspace has been renamed and a level-0
archive of the rootdbs and renamed dbspace is taken.
Mixed restores
A mixed restore is a cold restore followed by a warm restore. A mixed restore
restores some storage spaces during a cold restore (the database server is offline)
and some storage spaces during a warm restore (the database server is online). You
could do a mixed restore when you perform a full-system restore, but you need to
provide access to a particular table or set of tables as soon as possible. In this case,
perform a cold restore to restore the critical dbspaces and the dbspaces that contain
the important tables.
A cold restore takes less total time to restore all your data than a mixed restore,
even though the database server is online during part of a mixed restore because a
The dbspaces not restored during the cold restore do not become available until
after the database server restores them during a warm restore, even though a
critical dbspace possibly did not damage them.
You must run the ontape command as the owner of the database server: user
informix or root for a standard installation, or the owner of the non-root
installation. The owner of the database server for the restore must be the same as
the owner of the database server for the backup.
Syntax
ontape -r
-p Rename a chunk -t STDIO
-e -v
-D dbspace
-l -C
-X
-S
Rename a chunk:
In the file, list the old chunk path name and offset and the
new chunk path name and offset, with a blank space or a
tab between each item. Put information for each chunk on
a separate line. Blank lines are ignored. Begin comment
lines with a # symbol.
-l Directs ontape to perform a logical The -l option restores data from the logical-log backup
restore. tapes you created after (and including) your last level-0
backup.
-p Directs ontape to perform a physical The -p option restores data from the backup tape you
data restore. created after (and including) your last level-0 backup.
During the restore, the database server is in single-user
mode.
-p old_path Specifies the chunk to be renamed The variables for this element are:
and its new location. Use to rename
-o old_offset-n old_path
one or more chunks at one time.
new_path The current path and file name of the chunk.
old_offset
-o new_offset
The current offset of the chunk, in kilobytes.
new_path
The new path and file name of the chunk.
new_offset
The new offset of the chunk.
-r Directs ontape to perform a data The -r option restores data from the backup tape and the
restore (both physical and logical). logical-log backup tapes you created after (and including)
your last level-0 backup.
-rename Directs ontape to rename the For more information about renaming chunks during a
specified chunks. restore, see “Rename chunks during a restore” on page
13-10.
-S Directs ontape to perform a logical If you want to salvage logical logs, you must use the -S
log salvage. option before performing a restore from standard input.
The LTAPEDEV configuration parameter must be set to
the logical log tape device.
-t STDIO Directs ontape to restore from The -t option overrides the value of the TAPEDEV
standard input. configuration parameter for the current restore.
-v Directs ontape to write Verbose mode is useful for monitoring the progress of a
informational message to stderr restore from standard input.
during a restore from standard
input.
-X Quiesces a server in logical restore Include this option with -r -l to end continuous log restore
suspend state without restoring of logical logs.
additional logs.
When using ontape to create an archive backup of the system, a snapshot of the
logical logs is included with the archive. At the end of the archive, the system
displays a message that indicates what logical logs are included in the archive. The
snapshot is included in the archive so that if any open transactions exist at the
time of the backup, those transactions can be reconciled when the archive is
restored. Then:
v If you decide not to replay any logical logs, the system can be brought to a
consistent state.
v If you decide to replay logical logs, the logs contained within the archive backup
are discarded and you must replay transactions from the logical log backups.
The starting log file is the oldest log file containing an open transaction at the
time of the last restored archive. You can identify that log file from the message
that was displayed when the last archive was restored.
Example:
v The ontape -s -L 0 command performs a level-0 backup of the system and
displays a message that states that the archive contains logs 2-4.
v The ontape -s -L 1 command performs a level 1 incremental backup of the
system and displays a message that states that the archive contains logs 8-9.
The restore of the logical log files uses an archive format, not a log file format.
However, the logs contained within the restored archive are in log file format, not
an archive format.
When restoring from a file system directory, ontape requires that storage-space
archive and logical-log backup files be named as specified by the TAPEDEV and
LTAPEDEV configuration parameters. If files were renamed, including by ontape
because of repeated archives and backups, you must manually rename the files to
their original file names. To learn about the naming conventions for storage-space
archive files and logical-log backup files, see “Back up to a directory” on page 12-6
for the naming conventions of these files.
For guidance, use the copies of the configuration file that you create at the time of
each backup. However, do not set all current parameters to the same values as
were recorded at the last backup. Pay attention to the following three groups of
parameters:
v Shared-memory parameters
v Mirroring parameters
v Device parameters
For example, if you drop a dbspace or mirroring for a dbspace after your level-0
backup, you must make the dbspace or mirror chunk device available to the
database server when you begin the restore. When the database server attempts to
write to the chunk and cannot find it, the restore does not complete. Similarly, if
you add a chunk after your last backup, you must make the chunk device
available to the database server when it begins to roll forward the logical logs.
You must run the ontape command as the owner of the database server: user
informix or root for a standard installation, or the owner of the non-root
installation. The owner of the database server for the restore must be the same as
the owner of the database server for the backup.
Run the following ontape command to restore all the storage spaces: ontape -r
When you perform a mixed restore, you restore only some of the storage spaces
during the cold restore. You must restore at least all the critical dbspaces, as the
following example shows:
ontape -r -D rootdbs llogdbs plogdbs
You can avoid the prompt by using the ontape -d option. When using this option,
ensure that storage-space archive and logical-log backup files exist in the directory,
as specified by the TAPEDEV and LTAPEDEV parameters. The ontape utility scans
the directories for the files and uses them for the restore. After restoring the newest
applicable logical-log backup file, ontape automatically commits the restore and
brings the IBM Informix instance into quiescent mode.
When you perform a full restore, you can choose not to restore logical-log files.
When you do not back up your logical-log files or choose not to restore them, you
can restore your data only up to the state it was in at the time of your last backup.
For more information, see “Back up logical-log files with ontape” on page 12-13.
When you restore only some of your storage spaces during the cold restore, you
can start a warm restore of the remaining storage spaces after you bring the
database server online.
Backup tapes
Before you start your restore, gather together all the tapes from your latest level-0
backup that contain the storage spaces you are restoring and any subsequent
level-1 or level-2 backups.
Logical-log tapes
Gather together all the logical-log tapes from the logical-log backup after the latest
level-0 backup of the storage spaces you are restoring.
When you add a chunk after your last backup, you must ensure that the chunk
device is available to the database server when it rolls forward the logical logs.
After the warm restore, you must roll forward your logical-log files to bring the
dbspaces that you are restoring to a state of consistency with the other dbspaces in
the system. Failure to roll forward the logical log after restoring a selected dbspace
results in the following message from ontape:
Partial system restore is incomplete.
You must run the ontape command as the owner of the database server: user
informix or root for a standard installation, or the owner of the non-root
installation. The owner of the database server for the restore must be the same as
the owner of the database server for the backup.
To restore selected storage spaces, run the ontape command, with the options that
the following example shows:
ontape -r -D dbspace1 dbspace2
You cannot restore critical dbspaces during a warm restore; you must restore them
as part of a cold restore, described in “Restore the whole system” on page 13-5.
During the restore, ontape prompts you to mount tapes with the appropriate
backup files.
At the end of the warm restore, the storage spaces that were down go online.
The ontape rename chunk restore only works for cold restores.
The critical dbspaces (for example, the rootdbs) must be restored during a cold
restore. If you do not specify the list of dbspaces to be restored, then the server
restores the critical dbspaces and all the other dbspaces. But if you specify the list
of dbspaces to be restored, then the critical dbspaces must be included in the list.
For the syntax of renaming chunks with ontape, see “ontape utility syntax:
Perform a restore” on page 13-3.
Tip: If you use symbolic links to chunk names, you might not need to rename
chunks; you need only edit the symbolic name definitions. For more information,
see the IBM Informix Administrator's Guide.
You can rename chunks during an external cold restore. See “Rename chunks” on
page 14-5 for more information.
If either of the validation steps fails, the renaming process stops and ontape writes
an error message to the ontape activity log.
Important:
v Perform a level-0 archive after you rename chunks; otherwise your next restore
fails.
v If you add a chunk after performing a level-0 archive, that chunk cannot be
renamed during a restore. Also, you cannot safely specify that chunk as a new
path in the mapping list.
v Renaming chunks for database servers participating in HDR involves a
significant amount of offline time for both database servers. For more
information, see the IBM Informix Administrator's Guide.
Perform a level-0 archive after the rename and restore operation is complete.
Perform a level-0 archive after the rename and restore operation is complete.
Perform a level-0 archive after the rename and restore operation is complete.
You can combine renaming chunks with existing devices and renaming chunks
with nonexistent devices in the same rename operation. This example shows how
to rename a single chunk to a nonexistent device name.
The following table lists example values for the chunks used in this example.
Storage space Old chunk path Old offset New chunk path New offset
sbspace1 /chunk3 0 /chunk3N 0
When you perform a restore from standard input, ontape does not prompt you for
options or information. If ontape cannot perform the operation with the
information you provided in the restore command, ontape exits with an
appropriate error. Restoring from standard input differs from restoring from tapes
in the following ways:
v No logical restore or logical log salvage occurs.
To perform a logical restore, use the ontape -l command after the physical
restore.
To salvage logical logs, use the ontape -S command before the physical restore.
v You are not prompted to confirm the restore. Informational messages about the
archive are sent to stderr.
If you detect a problem, you can interrupt the restore during the 10 second
delay between the completion of the archive information and starting the
database server.
Examples
In the following example, ontape performs a physical restore from the file
level_0_archive, which contains the archive previously performed to standard
output:
cat /home/level_0_archive | ontape -p
When these restores are completed, the database server is left in single-user mode.
Related reference:
“Back up to standard output” on page 12-5
However, the process might hang after completing successfully. You have three
primary options:
v Terminate the remote shell process
v Execute the remote shell from the remote server with the following command:
rsh local_server "ontape -s -L 0 -F" | ontape -p
v Redirect the standard output (stdout) and standard error (stderr) on the remote
server with the following command from the sh or bash shell:
ontape -p >/dev/null 2>&1
To use standard I/O to perform the backup and restore, set the TAPEDEV
configuration parameter to STDIO, or you can specify -t STDIO from the command
line.
For example, if the TAPEDEV configuration parameter is set to STDIO, the following
command loads data into the secondary server on an HDR pair (named
secondary_host).
ontape -s -L 0 -F | rsh secondary_host "ontape -p"
In the next example, assume that the TAPEDEV configuration parameter is not set.
The following command loads data into the secondary server of an HDR pair
(named secondary_host):
ontape -s -L 0 -F -t STDIO | rsh secondary_host "ontape -t STDIO -p"
The examples perform a fake level-0 archive of the database server on the local
computer, pipe the data to the remote computer by using the rsh system utility,
and perform a physical restore on the remote computer by reading the data
directly from the pipe.
The ontape utility does not move the data during the backup or physical restore.
An external backup allows you to copy disks that contain storage-space chunks
without using ontape. When disks fail, replace them and use vendor software to
restore the data, then use ontape for the logical restore. For more information, see
“Data that is restored in an external restore” on page 14-3.
The following are typical scenarios for external backup and restore:
v Availability with disk mirroring
If you use hardware disk mirroring, you can get your system online faster with
external backup and restore than with conventional ontape commands.
v Cloning
You can use external backup and restore to clone an existing production system
for testing or migration without disturbing the production system.
The ontape utility treats an external backup as equivalent to a level-0 backup. You
cannot perform an external backup and then use ontape to perform a level-1
backup, or vice versa because ontape does not have any record of the external
backup. For more information, see “Performing a cold external restore” on page
14-5.
Important: Because the external backup is outside the control of ontape, you must
track these backups manually. For more information, see “Track an external
backup” on page 7-3.
Important: Because external backup is not done through ontape, you must
ensure that you have a backup of the current logical log from the time when
you execute the onmode -c block command. Without a backup of this
logical-log file, the external backup is not restorable.
5. After you perform an external backup, back up the current log. using the
ontape -a command.
If you lose a disk or the whole system, you are now ready to perform an external
restore.
You can only perform a cold external restore with ontape. A cold external restore
marks storage spaces as physically restored, then performs a logical restore of all
storage spaces.
To salvage logical logs, perform ontape -S before you copy the external backup
and perform the external restore (ontape -p -e).
-p -e
Use the ontape -l command to perform a logical restore. For more information, see
“ontape utility syntax: Perform a restore” on page 13-3.
Use the following commands to rename chunks during an external cold restore:
ontape -p -e -rename -f filename
or
ontape -p -e -rename -p old_path -o old_offset-n new_path-o new_offset
External restore
command Action Comments
ontape -p -e Physical external restore The system restores the logical logs
and logical restore from the oldest external backup.
ontape -l
ontape -p -e -rename -f External cold restore with
renamed chunks
The archecker utility restores tables by specifying the source table to be extracted,
the destination table where the data is placed, and an INSERT statement that links
the two tables.
For information about using the archecker utility to verify backups, see “onbar -v
syntax: Verifying backups” on page 5-13.
Related reference:
“The archecker utility configuration parameters and environment variable” on
page 16-24
The archecker utility is designed to recover specific tables or sets of tables. Other
situations require that you use different utilities. For example, use ON-Bar or
ontape in the following data recovery scenarios:
v Full system restore
v Recovery from disk failure
To configure the behavior of the archecker utility, use the archecker configuration
file. To define the schema of the data that archecker recovers, use the archecker
schema command file. These files are described in the following sections.
Set the AC_CONFIG environment variable to the full path name of the archecker
configuration file. By default, the AC_CONFIG environment variable is set to
$INFORMIXDIR/etc/ac_config.std. If you set AC_CONFIG to a user-defined file, you
must specify the entire path including the file name.
For information about the configuration parameters used in this file, see “The
archecker utility configuration parameters and environment variable” on page
16-24.
No code set conversion is performed during a table-level restore; the locale code
set of the database or table being restored must match the locale code set of the
database or table that the data is being restored to. In addition, the same DB_LOCALE
information is used for all of the tables being restored by using the same
table-level restore command schema file.
The two types of restores that the archecker utility performs are:
v A physical restore that is based on a level-0 archive.
v A physical restore followed by a logical restore, which uses both a level-0
archive and logical logs to restore data to a specific point in time.
The procedures and resources that archecker uses differ between a physical-only
restore and a physical and logical restore. These procedures are outlined in the
following sections.
Physical restore
When the archecker utility performs a physical restore, the utility extracts data
from a level-0 archive.
To restore a table with the original schema, the source schema must be specified.
To restore a table with a different schema, the table name in the target schema
must be different from the table name in the source schema. After restoring by
using a different schema, the table can be renamed with the rename table
statement.
Before performing a logical recovery, ensure that all transactions you want to
restore are contained in backed-up logical logs. The archecker utility cannot replay
transactions from the current log. You cannot perform a logical restore on an
external table.
When performing a logical restore, archecker uses two processes that run
simultaneously:
Stager Assembles the logical logs and saves them in tables.
Applier
Converts the log records to SQL statements and executes the statements.
The stager
To collect the pertinent logical log records, the stager performs the following steps:
1. Scans only the backed-up logical logs
The stager reads the backed-up logical log files and assembles complete log
records.
2. Tests the logical log records
Any log record that is not applicable to the tables being restored is rejected.
3. Inserts the logical log information in to a table
If the logical log record is not rejected, it is inserted into a stage table.
The applier
The applier reads data from the control table created by the stager. It begins
processing the required transaction and updates the control table to show that this
transaction is in process. Next, it operates on each successive log record, row by
row, until the transaction commits.
All updates to the control table occur in the same transaction as the log record
modification. This allows all work to be completed or undone as a single unit,
maintaining integrity at all times. If an error occurs, the transaction is rolled back
and the error is recorded in the control table entry for this transaction.
When data is being restored and the DBA has elected to include a logical restore,
two additional work columns and an index are added to the destination table.
These columns contain the original rowid and original part number. These columns
provide a unique key which identifies the location of the row on the original
After the applier has finished and the restore is complete, these columns, and any
indexes created on them, are dropped from the destination table.
Table-level restore:
-X
-f cmd_file -l phys
stage
apply
-D
When you use ON-Bar, you can use an ON-Bar command to access archecker
information to verify a backup. For information on the syntax for this command,
see “onbar -v syntax: Verifying backups” on page 5-13.
The following examples show how to perform a logical restore. In all examples, the
name of the schema command file is cmdfile.
After the physical restore is complete, the archecker utility starts the stager. After
the stager has started, the applier is automatically started.
In the following example, the -lstage option starts the archecker stager. The stager
extracts the logical log records from the storage manager and saves the applicable
records to a table.
archecker -bvs -f cmdfile -lstage
The stager should only be started after physical recovery has completed.
In the following example, the -lapply option starts the archecker applier. It looks
in the acu_control table for the transaction to recover. The applier should only be
started after the stager has been started.
archecker -bvs -f cmdfile -lapply
During a level-0 archive, there cannot be any open transactions that would change
the schema of the table. The table or table fragments being recovered must exist in
the level-0 archive. The table or fragment cannot be created or added during the
logical recovery. Tables created or fragments added during the logical recovery are
ignored.
Because a detached fragment is no longer part of the original table, the applier
does not process the detached fragment log record or any other log records for this
fragment from this point forward. A message in the archecker message log file
indicates a detach occurred.
You can remove the working files and tables by explicitly running the command
archecker -DX or by using the -d option when you run the next archecker
table-level restore command. The -d option indicates that all files and tables from
the previous run of archecker table-level restore are removed before the new
restore begins.
v ontape example: archecker -tdvs -fschema_command_file
v onbar example: archecker -bdvs -fschema_command_file
Use the schema command file to specify the source and destination tables and to
define the table schema.
Important: Standard SQL comments are allowed in the archecker utility file and
are ignored during processing.
Syntax
The syntax of the CREATE TABLE used in the archecker schema command file is
identical to the corresponding IBM Informix SQL statement. For a description of
this syntax, see the IBM Informix Guide to SQL: Syntax.
Usage
You must include the schema for the source table in the archecker schema
command file. This schema must be identical to the schema of the source table at
the time the archive was created.
The schema of the source table is not validated by archecker. Failing to provide an
accurate schema leads to unpredictable results.
The source table cannot be a synonym or view. The schema of the source table
only needs the column list and storage options. Other attributes such as extent
sizes, lock modes, and so on are ignored. For an ON-Bar archive, archecker uses
the list of storage spaces for the source table to create its list of objects to retrieve
from the storage manager. If the source table is fragmented, you must list all
dbspaces that contain data for the source table. The archecker utility only extracts
data from the dbspaces listed in the schema command file.
If the source table contains constraints, indexes, or triggers, they are automatically
disabled during the restore. Foreign constraints that reference the target table are
also disabled. After the restore is complete, the constraints, indexes, and triggers
are enabled. For better performance, remove constraints, indexes, and triggers prior
to performing a restore.
You must also include the schema of the target table in the command file. If the
target table does not exist at the time the restore is performed, it is created using
the schema provided.
Examples
The schema of the source and target tables do not have to be identical. The
following example shows how you can repartition the source data after performing
the data extraction:
CREATE TABLE source (col1 integer, ...) IN dbspace1;
CREATE TABLE target (col1 integer, ...)
FRAGMENT BY EXPRESSION
MOD(col1, 3) = 0 in dbspace3,
MOD(col1, 3) = 1 in dbspace4,
MOD(col1, 3) = 2 in dbspace5;
INSERT INTO target SELECT * FROM source;
Syntax
The syntax of the CREATE EXTERNAL TABLE statement for the archecker schema
file is not identical to the SQL CREATE EXTERNAL TABLE statement.
USING ( “filename“ ) ;
, DELIMITED
INFORMIX
Element Description
column The name of the column. Must conform to SQL identifier syntax rules.
For more information, see the IBM Informix Guide to SQL: Syntax.
data_type The built-in data type of the column. For more information about data
types, see the IBM Informix Guide to SQL: Reference.
filename Either the name of the file in which to place the data or a pipe device.
The pipe device must exist before starting the archecker utility.
name The name of the table to store the external data. Must be unique among
names of tables, views, and synonyms in the current database. Must
conform to SQL database object name rules. For more information, see
the IBM Informix Guide to SQL: Syntax.
Usage
When you use the CREATE EXTERNAL TABLE statement to send data to an
external table, the data is only extracted from a level-0 archive. Logical logs are not
rolled forward on an external table.
You can specify either of the following formats for external files:
For an example of using the CREATE EXTERNAL TABLE statement, see “Restore
to an external table” on page 15-15.
Syntax
DATABASE dbname ;
LOG MODE ANSI
Element Description
dbname The name of the current database.
Usage
Multiple DATABASE statements can be used. All table names referenced following
this statement are associated with the current database.
If the logging mode of the source database is ANSI and default decimal columns
are used in the table schemas, then the logging mode of the database must be
declared.
If the logging mode of the source database is not declared no error will be
returned, but unexpected results and data can occur.
Examples
In the following example, both the source and target tables reside in the same
database dbs.
DATABASE dbs;
CREATE TABLE source (...);
CREATE TABLE target (...);
INSERT INTO target SELECT * from source;
You can use multiple database statements to extract a table from one database into
another database.
DATABASE dbs1;
CREATE TABLE source (...) IN dbspace1;
DATABASE dbs2;
CREATE TABLE target (...) IN dbspace2;
INSERT INTO dbs2:target SELECT * FROM dbs1:source;
( target_column )
Element Description
filter The following filters are supported by the INSERT statement:
v =, !=, <>
v >, >=, <, <=
v [NOT] MATCHES, [NOT] LIKE
v IS [NOT] NULL
v AND, OR
v TODAY, CURRENT
Examples
The following example demonstrates the simplest form of the INSERT statement.
This statement extracts all rows and columns from the source to the target table.
INSERT INTO target SELECT * FROM source;
You can also extract a subset of columns. In the following example, only two
columns from the source table are inserted into the destination table.
CREATE TABLE source (col1 integer, col2 integer, col3 integer, col4 integer);
CREATE TABLE target (col1 integer, col2 integer);
INSERT INTO target (col1, col2) SELECT col3, col4 FROM source;
Element Description
"time" The date and time the table is to be restored to.
Usage
The TO clause is used to restore the table to a specific point in time, which is
specified by a date and time or the reserved word CURRENT.
Only one RESTORE statement can be specified in a command file. If this statement
is not present in the command file, then the system will be restored to the most
current time using logical logs.
Tip: Use this option when you do not have logical logs. You will not receive any
messages about logical recovery.
Example
RESTORE TO CURRENT WITH NO LOG;
Syntax
SET COMMIT TO number
,
WORKSPACE TO dbspace
Element Description
number Sets the number of records to insert before committing during a physical
restore. The default is 1000.
dbspace The dbspaces to use for the working storage space. The default is the
root dbspace. You cannot use temporary dbspaces for the working
storage space.
The archecker utility creates several tables for the staging of logical log records
during a logical restore. These tables are created in the sysutils database and
stored in the working storage space.
You set most of these configuration parameters in the onconfig file. However, you
set some of the archecker configuration parameters in the AC_CONFIG file.
Be sure to configure your storage manager. Depending on the storage manager that
you choose, you might set different ON-Bar configuration parameters. If you are
using a third-party storage manager, see “Configuring a third-party storage
manager” on page 4-8, before you start ON-Bar.
The following table describes the following attributes (if relevant) for each
parameter.
Attribute Description
ac_config.std value For archecker configuration variables. The
default value that appears in the
ac_config.std file.
onconfig.std value For onconfig configuration variables. The
default value that appears in the
onconfig.std file.
if value not present The value that the database server supplies if
the parameter is missing from your onconfig
file.
Related reference:
Part 2, “ON-Bar backup and restore system”
Usage
This filter transforms data before backing it up, such as compressing it. The
transformed data is then backed up and stored as a single file. When you perform
a restore, you must transform the data back to its original format. Specify the
appropriate program to transform data before a restore by setting the
RESTORE_FILTER configuration parameter.
For security purposes, filters should not have write permission to non-privileged
users. Permission on the filters is the same as that of permission on other
executable files that are called by the IBM Informix server or utilities.
Note: If the BACKUP_FILTER parameter is set in the onconfig file, the LTAPESIZE
configuration parameter cannot be set to 0. Otherwise the ON-Bar or ontape utility
returns an error when backing up logical logs to a directory on disk. The error
message is:
The LTAPESIZE configuration parameter cannot be set to 0 when the BACKUP_FILTER
configuration parameter is set; change the value of LTAPESIZE.
Program over.
Output produced by this filter is saved as a single object in the storage manager.
Usage
The sysbaract_log table is a system monitoring interface pseudo table that reads
data from the file specified by BAR_ACT_LOG. The following errors are returned
if you attempt to query the sysbaract_log on a system where the BAR_ACT_LOG
file does not exist:
244: Could not do a physical-order read to fetch next row.
101: ISAM error: file is not open.
For UNIX, if the database server launches a continuous logical-log backup, ON-Bar
writes to the ON-Bar activity log in the working directory for the database server.
Usage
ON-Bar and the storage manager rely on a shared library to integrate with each
other. Configure the BAR_BSALIB_PATH configuration parameter for your
storage-manager library. Support for BAR_BSALIB_PATH is platform-specific.
Check your machine notes to determine whether you can use this configuration
parameter with your operating system. You can change the value of
BAR_BSALIB_PATH between a backup and restore.
To ensure that this integration takes place, specify the shared-library path name.
Set one of the following options:
UNIX:
v Place the storage-manager library in the default directory.
For example, the suffix for Solaris is so, so you specify $INFORMIXDIR/lib/
ibsad001.so on a Solaris system.
v Place the storage-manager library in any directory and create a symbolic link
from $INFORMIXDIR/lib/ibsad001.platform_extension to it.
If you use IBM Informix Storage Manager (ISM) (ISM), create a symbolic link to
$INFORMIXDIR/lib/libbsa.platform_extension or set BAR_BSALIB_PATH to this
absolute path value.
If you use IBM Tivoli Storage Manager (TSM), create a symbolic link to
$INFORMIXDIR/lib/libtxbsa.platform_extension or set BAR_BSALIB_PATH to
this absolute path value.
v Set the LD_LIBRARY_PATH environment variable. For example, set LD_LIBRARY_PATH
to $INFORMIXDIR/lib.
Windows:
v Place the storage-manager library in the default directory.
v Set the path name for the ISM shared library to the installation directory for
ISM: %ISMDIR%\bin\libbsa.dll.
The %ismDIR% variable includes a version or release number. For example: set
ISMDIR=C:\program files\informix\ism\2.20. This directory is set when the
database server is installed on Windows. This path name is different if you use a
different storage manager.
Tip: Be sure that the shared library can access the backup data in the storage
manager in a restore. You cannot back up on to one storage manager and restore
from a different storage manager.
Usage
Usage
You can dynamically update the value of BAR_DEBUG in the onconfig file during
a session.
Related reference:
“BAR_DEBUG_LOG configuration parameter”
Usage
If you set the value to 0, onsmsync removes the bar_object, bar_action, and
bar_instance rows for the expired backup objects from the sysutils database. If you
set the value to 1, onsmsync sets the act_type value to 7 in the bar_action row and
keeps the bar_action and bar_instance rows for expired backup objects in the
sysutils database. If you do not set BAR_HISTORY to 1, the restore history is
removed.
For more information about onsmsync, see “The onsmsync utility” on page 8-4.
You can change the path to create the file in another location. For example, if you
want to create the ON-Bar boot file in the directory /usr/informix with the name
ixbar.new, specify:
BAR_IXBAR_PATH=/usr/informix/ixbar.new
To specify parallel backups and restores, including parallel whole system backups
and restores, set BAR_MAX_BACKUP to a value higher than 1. For example, if
you set BAR_MAX_BACKUP to 5 and execute an ON-Bar command, the
maximum number of processes that ON-Bar creates concurrently is 5. Configure
BAR_MAX_BACKUP to any number up to the maximum number of storage
devices or the maximum number of streams available for physical backups and
restores. ON-Bar groups the dbspaces by size for efficient use of parallel resources.
The value of this parameter affects ON-Bar performance. For example, if you set
BAR_NB_XPORT_COUNT to 5 and then issue five ON-Bar commands, the
resulting 25 ON-Bar processes use a total of 125 buffers.
To calculate the amount of memory that each onbar_d process requires, use the
following formula. For information about the page size for your system, see the
release notes:
required_memory = (BAR_NB_XPORT_COUNT * BAR_XFER_BUF_SIZE
* page_size) + 5 MB
Usage
For example, if you set BAR_PERFORMANCE to 3, ON-Bar reports the time spent
transferring data between the IBM Informix instance and the storage manager, in
the activity log. If you set BAR_PERFORMANCE to 0 or do not set it, ON-Bar does
not report performance statistics.
v To turn performance monitoring off, set the value to 0. This is the default.
v To display the time spent transferring data between the Informix instance and
the storage manager, set the parameter to 1.
v To display timestamps in microseconds, set the parameter to 2.
v To display both timestamps and transfer statistics, set the parameter to 3.
Related reference:
“View ON-Bar backup and restore performance statistics” on page 8-9
Usage
If ON-Bar cannot determine the size of the backup or restore object, it reports the
number of transfer buffers sent to the database server instead of the percentage of
the object backed up or restored.
Usage
Usage
The estimate is handled before the backup and is calculated so that the storage
manager can allocate the storage media appropriately. Because the backup is done
The formula used for calculating the new estimated backup object size is:
new_estimate = original_estimate x (1 + (BAR_SIZE_FACTOR / 100))
The value to which you set this parameter in a specific server environment
depends on the activity on the system during backup or archive. Therefore,
determining the value needs to be based on the individual experience with that
system.
Usage
The database server passes the transfer buffer to ON-Bar and the storage manager.
You can determine the system page size by running the onstat -b command.
The maximum size of the transfer buffer for most storage managers is 64 KB. IBM
Tivoli Storage Manager (TSM) supports long transfer buffer sizes of up to 65532
KB.
The extra 500 bytes is for system use. For example, if BAR_XFER_BUF_SIZE is 15,
the transfer buffer can be 66,292 bytes, or 64.5 KB.
The number of transfer buffers per backup stream is specified by the value of the
BAR_NB_XPORT_COUNT configuration parameter, and the number of parallel
backup streams is specified by the BAR_MAX_BACKUP configuration parameter.
Restriction: You cannot change the buffer size between a backup and restore. The
values of the AC_TAPEBLOCK and AC_LTAPEBLOCK configuration parameters
must be the same value as the value of the BAR_XFER_BUF_SIZE configuration
parameter was at the time of backup.
Example
For example, for a transfer buffer size of 128*2 KB (a value of 256 KB) on Linux,
specify:
BAR_XFER_BUF_SIZE 128
Related concepts:
“Configuring ON-Bar for optional TSM features” on page 4-7
Related reference:
onstat -b command: Print buffer information for buffers in use (Administrator's
Reference)
setenv IFX_BAR_NO_BSA_PROVIDER 1
By default, ON-Bar communicates directly with the XBSA library for some storage
managers. ON-Bar does not require that the sm_versions file is updated to contain
information about the XBSA library for those storage managers.
setenv IFX_BAR_NO_LONG_BUFFERS 1
setenv IFX_BAR_USE_DEDUP
You are not required to set the IFX_BAR_USE_DEDUP environment variable to a value.
You can set it to any value or to no value.
After you unset the IFX_BAR_USE_DEDUP environment variable, you must perform a
level-0 backup.
Related concepts:
“Configuring ON-Bar for optional TSM features” on page 4-7
Related tasks:
“Configuring a third-party storage manager” on page 4-8
Related reference:
“Editing the TSM client system options file” on page 4-4
Chapter 11, “Configure ontape,” on page 11-1
setenv IFX_TSM_OBJINFO_OFF 1
By default, ON-Bar stores unique IDs in the metadata of backup objects that are
created by TSM. During a restore, ON-Bar checks the metadata to identify the
object. Therefore, ON-Bar can restore a backup whose original ID, which is stored
as CopyID columns in the ON-Bar catalog, changed because the object was
replicated, exported, or imported between TSM servers. To prevent the ability to
restore backup objects that are moved between TSM servers, set the
IFX_TSM_OBJINFO_OFF environment variable to 1.
Usage
The value for this parameter can be any volume pool that IBM Informix Storage
Manager (ISM) (ISM) recognizes. If this parameter is not present, ISM uses the
ISMData volume pool. For details, see the IBM Informix Storage Manager
Administrator's Guide.
Usage
The value for this parameter can be any volume pool that IBM Informix Storage
Manager (ISM) (ISM) recognizes. If this parameter is not present, ISM uses the
ISMLogs volume pool. For details, see the IBM Informix Storage Manager
Administrator's Guide.
LTAPEBLK also specifies the block size for the device to which data is loaded or
unloaded when you use the -l option of onload or onunload. If you are using
onload or onunload, you can specify a different block size at the command line.
onconfig.std value
v On UNIX: 32
v On Windows: 16
units Kilobytes
range of values
Values greater than (page size/1024)
To obtain the page size, run the onstat -b command.
takes effect
For ontape:
v When you execute ontape.
v When you reset the value dynamically in your onconfig file by running
the onmode -wf command.
For onload and onunload: When the database server is shut down and
restarted
Usage
Specify LTAPEBLK as the largest block size permitted by your tape device. The
database server does not check the tape device when you specify the block size.
Verify that the LTAPEDEV tape device can read the block size that you specify. If
not, you might not be able to read from the tape.
UNIX only: The UNIX dd utility can verify that the LTAPEDEV tape device can
read the block size. It is available with most UNIX systems.
Usage
Warning: Do not set LTAPEDEV to /dev/null or nul when you use ON-Bar to back
up logical logs.
If you performed a whole-system backup with LTAPEDEV set to null, you must
use the onbar -r -w -p command during restore to notify ON-Bar that you do not
want to restore the logs. .
Related concepts:
The onunload and onload utilities (Migration Guide)
Related reference:
“Changing your ontape configuration” on page 11-6
“LTAPEBLK configuration parameter” on page 16-16
The LTAPESIZE configuration parameter also specifies the maximum tape size of
the device to which data is loaded or unloaded when you use the -l option of
onload or onunload. If you are using onload or onunload, you can specify a
different tape size on the command line. If you want to use the full capacity of a
tape, set LTAPESIZE to 0.
onconfig.std value
0
units Kilobytes
range of values
0 or any positive number. The real value operating system dependent.
takes effect
For ontape:
v When you execute ontape.
v When you reset the value dynamically in your onconfig file by running
the onmode -wf command.
For onload and onunload: When the database server is shut down and
restarted
Usage
LTAPESIZE specifies the maximum tape size of the device to which the logical logs
are backed up when you use ontape for backups. LTAPESIZE also specifies the
maximum tape size of the device to which data is loaded or unloaded when you
use the -l option of onload or onunload. If you are using onload or onunload, you
can specify a different tape size on the command line. If you want to use the full
capacity of a tape, set LTAPESIZE to 0.
Usage
This filter transforms data that was transformed during backup to its original
format prior to a restore. The filter specified by the RESTORE_FILTER
For security purposes, filters should not have write permission to non-privileged
users. Permission on the filters are the same as that of permission on other
executable files that are called by the IBM Informix server or utilities.
For example, if you want to compress backed up data, you could set the
BACKUP_FILTER and RESTORE_FILTER configuration parameters to the
following values:
BACKUP_FILTER /bin/compress
RESTORE_FILTER /bin/uncompress
Usage
TAPEBLK also specifies the default block size of the device to which data is loaded
or unloaded when you use the onload or onunload utilities. If you are using
onload or onunload, you can specify a different block size on the command line.
The database server does not check the tape device when you specify the block
size. Verify that the TAPEBLK tape device can read the block size that you specify.
If not, you might not able to read from the tape.
16-20 IBM Informix Backup and Restore Guide
If you specify a TAPEBLK value, ON-Bar ignores the value.
Related concepts:
The onunload and onload utilities (Migration Guide)
Related reference:
“Changing your ontape configuration” on page 11-6
onmode -wf, -wm: Dynamically change certain configuration parameters
(Administrator's Reference)
“TAPEDEV configuration parameter”
“TAPESIZE configuration parameter” on page 16-23
“LTAPEBLK configuration parameter” on page 16-16
Part 3, “ontape backup and restore system”
Usage
The ontape utility reads the value of the TAPEDEV parameter at the start of
processing. If you set TAPEDEV to /dev/null, you must do it before you start
ontape to request the backup. When you set TAPEDEV to /dev/null and request a
backup, the database server bypasses the backup but still updates the dbspaces
with the new backup time stamps.
You can set the TAPEDEV configuration parameter to STDIO to direct ontape utility
back up and restore operations to standard I/O instead of to a device.
If you change the tape device, verify that the TAPEBLK and TAPESIZE
configuration parameter values are correct for the new device.
You can perform a storage-space backup across your network to a remote device
attached to another host computer on UNIX and Linux platforms. The remote
device and the database server computer must have a trusted relationship so that
the rsh or the rlogin utility can connect from the database server computer to the
remote device computer without asking for password. You can establish a trusted
relationship by configuring the /etc/hosts.equiv file, the user's ~/.rhosts files, or
any equivalent mechanism for your system on the remote device computer. If you
want to use a different utility to handle the remote session than the default utility
used by your platform, you can set the DBREMOTECMD environment variable to the
specific utility that you want to use.
Use the following syntax to specify a tape device attached to another host
computer:
host_machine_name:tape_device_pathname
The following example specifies a tape device on the host computer kyoto:
kyoto:/dev/rmt01
When the database server attempts to write to any tape other than the first tape in
a multivolume dbspace or logical-log backup, the database server first reads the
tape header to make sure that the tape is available for use. Then the device is
closed and reopened. The database server assumes the tape was rewound when it
closed, and the database server begins to write.
Whenever the database server attempts to read a tape, it first reads the header and
looks for the correct information. The database server does not find the correct
header information at the start of the tape if the tape device did not rewind when
it closed during the write process.
Related concepts:
The onunload and onload utilities (Migration Guide)
Related reference:
16-22 IBM Informix Backup and Restore Guide
“Changing your ontape configuration” on page 11-6
“TAPEBLK configuration parameter” on page 16-20
onmode -wf, -wm: Dynamically change certain configuration parameters
(Administrator's Reference)
“LTAPEDEV configuration parameter” on page 16-16
Part 3, “ontape backup and restore system”
Usage
The TAPESIZE also specifies the size of the default device to which data is loaded
or unloaded when you use onload or onunload. If you are using onload or
onunload, you can specify a different tape size on the command line. If you want
to use the full physical capacity of a tape, set TAPESIZE to 0.
Because ON-Bar calls the archecker utility to verify backups, you must configure
the archecker environment variable and parameters before you can use the onbar
-v option.
You can also use other archecker configuration parameters that do not have
default have default values in the ac_config.std file, but are valid in that file.
Table 16-1. Configuration parameters that the archecker utility uses
Configuration parameter Description
AC_DEBUG Prints debugging messages in the archecker message log.
AC_IXBAR Specifies the path name to the IXBAR file.
default value
UNIX: $INFORMIXDIR/etc/ac_config.std
Windows: %INFORMIXDIR%\etc\ac_config.std
takes effect
When ON-Bar starts
If AC_CONFIG is not set, the archecker utility sets the default location for the
archecker configuration file to $INFORMIXDIR/etc/ac_config.std on UNIX or
%INFORMIXDIR%\etc\ac_config.std on Windows.
Important: If you do not specify the entire path, including the configuration file
name in the AC_CONFIG file, the archecker utility might not work correctly.
The use of this configuration parameter can cause the archecker message log file to
grow very large and can substantially slow down archecker processing.
Default value
Off
Range 1-16
Usage
When you perform an archive with:
v onbar -b, the value of AC_TAPEBLOCK should be the value the
BAR_XFER_BUF_SIZE configuration parameter multiplied by the current page
size. For more information, see “BAR_XFER_BUF_SIZE configuration parameter”
on page 16-12.
v ontape -t, the value of AC_LTAPEBLOCK should be the value that the TAPEBLK
ONCONFIG configuration parameter was set to at the time of the archive. For
more information, see “Specify the tape-block-size” on page 11-5.
AC_LTAPEDEV parameter
Use the AC_LTAPEDEV configuration parameter to specify the local device name
that is used by the ontape utility.
If the tape device is set to STDIO, archecker receives input from standard input.
Default value
None
Range Any valid path name or STDIO
Usage
You must specify the entire path of the message log in the AC_CONFIG file or else
the archecker utility might not work correctly.
Usage
You must specify the entire path of the storage location in the AC_CONFIG file or else
the archecker utility might not work correctly.
The following table lists the directories and files that archecker builds. If
verification is successful, these files are deleted.
Table 16-2. The archecker temporary files
Directory Files
CHUNK_BM Bitmap information for every backed up storage space.
INFO Statistical analysis and debugging information for the backup.
SAVE Partition pages in the PT.######## file.
To calculate the amount of free space that you need, see “Temporary space for
backup verification” on page 5-15. It is recommended that you set AC_STORAGE
to a location with plenty of free space.
Usage
If the tape device is set to STDIO, archecker receives input from standard input.
Default value
None
Range Any valid path name or STDIO
The database server does not show errors in standard output (stdout) if an error
occurs when you use onbar -b to back up storage spaces or onbar -r to restore
storage spaces. Therefore, when you use onbar -b or onbar -r, you must check
information in the ON-Bar activity log (bar_act_log). As ON-Bar backs up and
restores data, it writes progress messages, warnings, and error messages to the
bar_act.log.
During an archive, the database server validates every page before writing it to the
archive device. This validation checks that the elements on the page are consistent
with the expected values. When a page fails this validation, a message similar to
the following is written to the online.log file:
16:27:49 Assert Warning: Archive detects that page 1:10164 is corrupt.
16:27:49 Who: Session(5, informix@cronus, 23467, 10a921048)
Thread(40, arcbackup1, 10a8e8ae8, 1)
File: rsarcbu.c Line: 2915
16:27:49 stack trace for pid 23358 written to /tmp/af.41043f4
16:27:49 See Also: /tmp/af.41043f4
16:27:49 Archive detects that page 1:10164 is corrupt.
16:27:50 Archive on rootdbs Completed with 1 corrupted pages detected.
The archive stops after detecting 10 corrupt pages. The online.log file displays the
full error message, including the page address, for the first 10 errors. Subsequently,
only the count of the number of corrupt pages is put in to the online.log.
After you receive this message, identify which table the corrupt page belongs to by
examining the output of the oncheck –pe command. To determine the extent of the
corruption, execute the oncheck –cID command for that table.
A corrupt page is saved onto the backup media. During a restore, the corrupt page
is returned in its corrupt form. No errors messages are written to the online.log
when corrupt pages are restored, only when they are archived.
To solve this problem, check if the database server is still running. If it is, shut
down the database server and run the command again.
Time lines use the UNIX time as the archive checkpoint time for dbspaces and the
closing time for logical logs. If logs are not automatically backed up and the
system clock is changed, the time line can get corrupted.
For example, if you have logical logs that were closed before the archive
checkpoint time, they have a timestamp that is higher than the archive checkpoint
time. The dbspace does not need the logs and ON-Bar will try to restore the
backup immediately. if a log cannot be found, ON-Bar fails with the following
message: There are no storage spaces or logical logs to backup or restore.
To use a new version of a third-party storage manager with the database server:
1. Install the new storage manager before you bring up the database server.
2. Update the sm_versions file with the new storage-manager definition.
Verify that the new storage manager operates correctly before you use it in a
production environment:
v Make sure that the storage manager can find the backup objects that ON-Bar
requests.
v Make sure that the new storage-manager version is able to read media written
with your old version.
Use the onsmsync utility to expire old backup history in the sysutils database and
emergency boot files.
Related tasks:
“Backing up before a database server or storage-manager upgrade” on page B-1
ON-Bar supports working with multiple storage managers at the same time. To set
up to test one storage manager and keep the other as a backup storage manager,
specify information for both of the storage managers in the BAR_BSALIB_PATH
configuration parameter and in the $INFORMIXDIR/etc/sm_versions file.
If you cannot use the old and new storage managers at the same time, use ON-Bar
and ISM or ontape as an alternative for backups while you check that backup and
restore operations work correctly with the new storage manager. Until you confirm
that the new storage manager works correctly, perform all your backups as whole
system level-0 backups (onbar -b -L 0 -w)
If you change physical connectivity, such as moving a storage device from a local
connection to a network server, make sure the new storage manager can move the
data across the network. Also ensure that the new storage manager can send
multiple data streams to storage devices. It also might use a different version of
XBSA.
Related tasks:
“Backing up before a database server or storage-manager upgrade” on page B-1
ON-Bar must run on the same computer as the database server. However, you can
run ON-Bar in any locale for which you have the supporting message and
globalization files. For example, if the server locale is English and the client locale
is French, you can issue ON-Bar commands in French.
The following command performs a level-0 backup of the dbspaces specified in the
file, tomb: onbar -b -L 0 -f tomb
On Windows, you cannot use multibyte file names in backup or restore commands
because they are not supported.
The sysutils database, the emergency boot files, and the storage-manager boot file
are created with the en_us.8859-1 (default English) locale. The ON-Bar catalog
tables in the sysutils database are in English. Change the client and database
locales to en_us.8859-1 before you attempt to connect to the sysutils database with
DB-Access or third-party utilities.
The IBM Informix GLS User's Guide describes the SQL identifiers that support
non-ASCII characters. Non-ASCII characters include both 8-bit and multibyte
characters.
For example, you can specify a non-ASCII file name for the ON-Bar activity login
BAR_ACT_LOG and a non-ASCII path name for the storage-manager library in
BAR_BSALIB_PATH.
If you do not set these environment variables, ON-Bar uses the date and time
format of the client locale.
If you perform a point-in-time restore, enter the date and time in the format
specified in the GL_DATETIME environment variable if it is set.
Accessibility features
The following list includes the major accessibility features in IBM Informix
products. These features support:
v Keyboard-only operation.
v Interfaces that are commonly used by screen readers.
v The attachment of alternative input and output devices.
Keyboard navigation
This product uses standard Microsoft Windows navigation keys.
In dotted decimal format, each syntax element is written on a separate line. If two
or more syntax elements are always present together (or always absent together),
the elements can appear on the same line, because they can be considered as a
single compound syntax element.
Each line starts with a dotted decimal number; for example, 3 or 3.1 or 3.1.1. To
hear these numbers correctly, make sure that your screen reader is set to read
punctuation. All syntax elements that have the same dotted decimal number (for
example, all syntax elements that have the number 3.1) are mutually exclusive
alternatives. If you hear the lines 3.1 USERID and 3.1 SYSTEMID, your syntax can
include either USERID or SYSTEMID, but not both.
The dotted decimal numbering level denotes the level of nesting. For example, if a
syntax element with dotted decimal number 3 is followed by a series of syntax
elements with dotted decimal number 3.1, all the syntax elements numbered 3.1
are subordinate to the syntax element numbered 3.
The following words and symbols are used next to the dotted decimal numbers:
? Specifies an optional syntax element. A dotted decimal number followed
by the ? symbol indicates that all the syntax elements with a
corresponding dotted decimal number, and any subordinate syntax
elements, are optional. If there is only one syntax element with a dotted
decimal number, the ? symbol is displayed on the same line as the syntax
element (for example, 5? NOTIFY). If there is more than one syntax element
with a dotted decimal number, the ? symbol is displayed on a line by
itself, followed by the syntax elements that are optional. For example, if
you hear the lines 5 ?, 5 NOTIFY, and 5 UPDATE, you know that syntax
elements NOTIFY and UPDATE are optional; that is, you can choose one or
none of them. The ? symbol is equivalent to a bypass line in a railroad
diagram.
! Specifies a default syntax element. A dotted decimal number followed by
the ! symbol and a syntax element indicates that the syntax element is the
default option for all syntax elements that share the same dotted decimal
number. Only one of the syntax elements that share the same dotted
decimal number can specify a ! symbol. For example, if you hear the lines
2? FILE, 2.1! (KEEP), and 2.1 (DELETE), you know that (KEEP) is the
default option for the FILE keyword. In this example, if you include the
FILE keyword but do not specify an option, default option KEEP is applied.
A default option also applies to the next higher dotted decimal number. In
this example, if the FILE keyword is omitted, default FILE(KEEP) is used.
However, if you hear the lines 2? FILE, 2.1, 2.1.1! (KEEP), and 2.1.1
(DELETE), the default option KEEP only applies to the next higher dotted
decimal number, 2.1 (which does not have an associated keyword), and
does not apply to 2? FILE. Nothing is used if the keyword FILE is omitted.
* Specifies a syntax element that can be repeated zero or more times. A
dotted decimal number followed by the * symbol indicates that this syntax
element can be used zero or more times; that is, it is optional and can be
Notes:
1. If a dotted decimal number has an asterisk (*) next to it and there is
only one item with that dotted decimal number, you can repeat that
same item more than once.
2. If a dotted decimal number has an asterisk next to it and several items
have that dotted decimal number, you can use more than one item
from the list, but you cannot use the items more than once each. In the
previous example, you can write HOST STATE, but you cannot write HOST
HOST.
3. The * symbol is equivalent to a loop-back line in a railroad syntax
diagram.
+ Specifies a syntax element that must be included one or more times. A
dotted decimal number followed by the + symbol indicates that this syntax
element must be included one or more times. For example, if you hear the
line 6.1+ data-area, you must include at least one data area. If you hear
the lines 2+, 2 HOST, and 2 STATE, you know that you must include HOST,
STATE, or both. As for the * symbol, you can repeat a particular item if it is
the only item with that dotted decimal number. The + symbol, like the *
symbol, is equivalent to a loop-back line in a railroad syntax diagram.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs.
© Copyright IBM Corp. _enter the year or years_. All rights reserved.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
This Software Offering does not use cookies or other technologies to collect
personally identifiable information.
If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.
For more information about the use of various technologies, including cookies, for
these purposes, see IBM’s Privacy Policy at http://www.ibm.com/privacy and
IBM’s Online Privacy Statement at http://www.ibm.com/privacy/details the
section entitled “Cookies, Web Beacons and Other Technologies” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the web at "Copyright and
trademark information" at http://www.ibm.com/legal/copytrade.shtml.
Notices E-3
Adobe, the Adobe logo, and PostScript are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other
countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Index X-3
Expiration policy 8-4 finderr utility 10-1
retention date 8-4
retention generation 8-4
retention interval 8-4
Expiring backups
G
GL_DATE environment variable C-2
all 8-7
GL_DATETIME environment variable C-2
generation of 8-7
Global Language Support (GLS) C-1
multiple Point-in-Time restores 8-7
on ISM 8-6
retention date 8-7
retention interval 8-7 H
using onsmsync 8-7 Hardware resources, evaluating 2-4
External backup HDR.
blocking database server 7-3, 14-2 external backup and restore 7-9
defined 7-2, 14-1 High-Availability Data Replication
procedure 7-4, 14-2 imported restore 6-15
RS secondary server 7-5 initializing 6-15
rules for 7-2 initializing with external restore 7-9, 14-5
tracking backup objects 7-3, 14-3
unblocking database server 7-3, 14-2
External backup and restore
cloning 7-1, 14-1
I
I/O
defined 7-1
simultaneous backup and restore 13-14
disk mirroring 7-1, 14-1
environment variables 13-14
initializing HDR 7-9
example 13-14
ON-Bar 7-1
secondary host 13-14
ontape 14-1
IBM Informix Storage Manager
recovering data 7-1, 14-1
overview 3-5
recovering data, procedure 7-1
IBM Informix Storage Manager (ISM)
External programs
backup requests 5-8
filters 2-6
configuring 4-2
transforming data with 2-6
ISM catalog 5-8
External restore
requirements 3-6
cold restore 14-3
IFX_BAR_NO_BSA_PROVIDER environment variable 16-13
cold restore procedure 7-8, 14-5
IFX_BAR_NO_LONG_BUFFERS environment variable 16-13
examples 7-9, 14-5
IFX_BAR_USE_DEDUP environment variable 16-14
initializing HDR during 7-9, 14-5
IFX_ONTAPE_FILE_PREFIX environment variable 12-6
ON-Bar, renaming chunks 7-9
IFX_TSM_OBJINFO_OFF environment variable 16-15
ontape utility
ifxbkpcloud.jar utility 12-11
-e command 14-3
Imported restore 6-15
-l command 14-3
ixbar.51 6-15
-p command 14-3
ixbar.52 6-15
performing 14-5
performing 6-15
prerequisites 14-4
Incremental backup
restored components 14-3
defined 2-2
rules 14-4
industry standards xiii
salvaging logical logs 7-8
INFORMIXSQLHOSTS environment variable 9-5
syntax diagram 7-6, 14-4
INSERT statements
warm restore procedure 7-8
archecker syntax 15-12
External tables
physical-only restores 15-12
CREATE EXTERNAL TABLE statement 15-10
ISM
restoring
environment variables 4-2
schema command file example 15-15
onconfig 4-2
sm_versions file 4-3
storage-manager definition 4-3
F ISM catalog
File directory, ontape backing up 5-8
syntax to specify 11-4 ism_catalog command 5-8, 6-2
Files ISM_DATA_POOL configuration parameter 16-15
ixbar 3-4 ISM_LOG_POOL configuration parameter 16-15
logical log 1-2 ism_watch command 5-8, 6-2
ON-Bar boot 3-4 ixbar boot file 3-4
onbar.bat 3-4 IXBAR file, specifying location of 16-26
Files for ON-Bar 4-12
Filters
for compression 2-6
transforming data 2-6
Index X-5
ON-Bar tables (continued) onstat -d command 6-2
bar_ixbar 9-5 onstat -l command 5-8
bar_object 9-5 ontape utility
map 9-6 -C option 13-3
ON-Bar utility -d option 12-7
-O option -D option 1-8, 13-3
onbar 5-2 -F option 12-7
restore 5-8, 6-3 -L option 12-7
whole-system restore 6-3 -s option 12-5
activity log 10-2 -t option 12-7
archecker -v option 12-7
setting configuration parameters 16-24 -X option 13-3
backup and restore time 2-4 backing up logical log 12-13
catalog tables 3-3 backup levels 12-2
compared to ontape 1-8 backups and modes 12-4
components 3-1 changing
configuration parameters 4-10, 16-19 database logging status 12-1
configuration parameters for 16-2 LTAPEDEV to /dev/null 16-17
deleting bad backups 8-7 TAPEDEV to /dev/null 16-21
external backup and restore 7-1 checking configuration parameters 11-6
monitoring restores compared to ON-Bar 1-8
onstat -d 6-2 configuration parameters 11-1
operations supported 1-8 configuration parameters for 16-2
planning recovery strategy creating an archive 12-2
creating backup plan 1-8 device name 15-1
data loss 2-2 ensuring adequate memory 12-5
data usage 2-1 example 16-28
failure severity 2-2 exit codes 12-9
pre-recovery checklist 6-1 external backup and restore 14-1
progress feedback 3-4 fake backup 12-7
restore labelling backup tapes 12-4
-e option 6-3 LTAPEBLK, uses 16-16
-f option 6-3 LTAPEDEV, uses 16-17
-i option 6-3 LTAPESIZE, uses 16-18
-I option 6-3 migrating to ON-Bar 12-4
-n option 6-3 option
-O option 6-3 -L 13-3
-q option 6-3 -r 12-7
-r option 6-3 -s 13-3
-t option 6-3 overview 14-3
-w option 6-3 parameters
storage management 3-5 changing 12-7
switching from ontape B-2 overriding 12-7
XBSA 3-3 parameters, changing 11-6
onbar -b 5-2 performing a restore 13-3
onbar script 8-1 physical restore, choosing type 13-1
updating 8-2 precautions, one tape device 13-1
usage and examples 9-1 premature backup termination 12-1
onbar syntax read to end of tape 12-14
-RESTART 6-19 restore, choosing mode 11-3, 13-1
onbar_m utility restoring data 13-2
defined 3-4 standard output 12-7
onbar-driver starting continuous backup 12-13
defined 3-4 syntax
oncfg file 5-2 full backup 12-14
Online storage spaces, restoring 6-3 logical-log backup 12-1
onmode -c TAPEBLK, uses 16-20
block command 7-3, 14-2 TAPEDEV, uses 16-21
unblock command 7-3, 14-2 TAPESIZE, uses 16-23
onmode -ky command 6-9 writing to end of tape 12-14
onmode -l command 5-8 onunload utility
onsmsync utility LTAPEBLK, uses 16-16
archecker 5-17 LTAPEDEV, uses 16-17
commands 8-4 LTAPESIZE, uses 16-18
syntax 8-4 TAPEBLK, uses 16-20
using 8-3 TAPEDEV, uses 16-21
onsmsync, expiring old backups 8-7 TAPESIZE, uses 16-23
Index X-7
S Standard output
backing up to 12-5
Salvaging logs setting TAPEDEV 11-5
example 1-3 standards xiii
skipping 6-8 stdio TAPEDEV setting 11-5
Sample-code conventions 6-8 Storage devices
Save sets ISM volume pools 5-8
defined 5-8 Storage manager
sbspaces communication with ON-Bar 4-1
archecker 5-15 migration B-1
backing up 6-2 onbar -P
verifying 5-13 viewing backed-up logical logs 5-11
Scheduling backups 2-3, 2-4 requirements B-1
Schema command file sm_versions file 4-8
example 15-15 Storage managers
restoring to a different a table 15-14 ON-Bar 3-5
restoring to an external table 15-14, 15-15 Storage spaces
simple 15-15 backing up a list 5-2
using data filtering 15-14 backing up all 5-2, 5-7
setting 15-14 restartable restore 6-19
Schema command file example restoring 1-5
extracting a subset of columns 3-7 when to back up 12-14
performing a distributed restore 15-14 Symbolic links
restoring a table from previous backup 15-16 chunking names 13-10
Schema file ontape utility
archecker 15-2 specify tape devices 11-4
CREATE EXTERNAL TABLE statement 15-10 specify tape size 11-5
Scratch table restoring chunk files 6-13
backing up 15-2 using with TAPEDEV configuration parameter 16-21
Screen reader Syntax diagrams
reading syntax diagrams D-1 backup verification 5-13, 15-5
scripts external restore 7-6, 14-2
onbar 8-1 onsmsync 8-4
Scripts reading in a screen reader D-1
backup and restore 3-4 restore 6-3
onbar 3-4 System time changes, and backups A-3
Server locale C-1 sysutils database
SERVERNUM configuration parameter 6-15 regenerating 8-7
SET statement
examples 15-13
syntax 15-13
Severity of data loss 15-13 T
Shared libraries, XBSA Tables
specifying location 4-9, 16-4 altering
Shared-memory parameters or adding during logical restore 15-7
setting to maximum assigned value 13-6 restoring to user-specified point in time 15-7
Shortcut keys Tables and fragments
keyboard D-1 added or created during logical recovery 15-7
Silos 4-9 not processed by applier during logical restore 15-7
Skipping Tape autochangers 3-6
log salvage 1-3 Tape block size
logical replay 6-8 ON-Bar utility 15-4
sm_versions file 4-1, 4-7 ontape utility 16-26
defining storage manager 5-2 Tape device
Smart large objects ontape utility
Restoring 15-8 before opening and on closing 11-5
sqlhosts file block-size parameters 11-5, 16-26
copying 5-2 gathering for cold restore 11-5
Stager, manually controlling logical restore using 9-5, 15-4 gathering for warm restore 11-5
Standard backup 15-4 parameters, setting 11-1
Standard input precautions with only one 11-3
overriding TAPEDEV 13-3 reading to end 11-3
restoring 13-13 rewindable device 11-3
example 13-13 specifying symbolic links 11-5
single-user mode 13-13 using /dev/null 11-5
setting TAPEDEV 11-5 setting TAPEDEV to stdio 11-5
simultaneous backup and restore 13-14 writing to end 11-4
Tape device, block size 16-16
U
Unblocking database server 7-3
UNIX operating system
bargroup 4-11
copying files 4-9, 4-11
Upgrading database server 7-4
Using CREATE EXTERNAL TABLE statement 15-10
Using CREATE TABLE statement 15-9
Using DATABASE statement 15-11
Using mixed restore, strategies 6-10
Index X-9
X-10 IBM Informix Backup and Restore Guide
Printed in USA
SC27-3542-05
Spine information:
Informix Product Family Informix Version 11.70 IBM Informix Backup and Restore Guide