Checkpoint Template File Description
The checkpoint template file drives the checkpoint and roll forward operations. If needed, you can tailor the file to meet the requirements of your site.
For example, if the database exists on multiple locations, checkpointing backs up each location to a separate tape or disk and, in turn, roll forward restores each location one at a time. If you want to use a different backup method or only one tape for all locations, you can edit this command file.
Checkpoint Template Codes
In the checkpoint template file, a four-character uppercase code at the beginning of each line provides the following information:
The first character indicates when the command is to be used. Valid characters are:
B (Begin)—the command is to be executed before the device is used. It indicates setup work done prior to the execution of the command.
P (Prework)—the command is to be executed before the work is executed.
I—the command begins table-level recovery (initializes only).
W (Work)—the command activates the device. It indicates the execution of the command.
F—the command ends table-level recovery (comments only).
E (End)—the command is executed after the device is used. It indicates cleanup work done after the operation is complete.
The second character indicates whether the command specifies several types of checkpointing and roll forward options. Valid characters are:
S—the command is for checkpointing only.
R—the command is for roll forward only.
E—the command is for both checkpointing and roll forward.
D—the command is for delete file processing.
C—the command checks if a database checkpoint exists before the roll forward.
J—journals are to be applied, for a roll forward.
U—dumps are to be applied, for a roll forward.
M—the command is for relocatedb operation only.
The third character specifies the device. Valid characters are:
T—the command on that line refers to reading from or writing to a tape.
D—the command refers to disk operations.
E—the command applies to both types of devices.
The fourth character specifies the data. Valid characters are:
D—the command is for a database.
A—the command is for all databases.
T—the command is for table(s).
E—the command is for either a database or table.
R—the command is for a raw location (database and table level are the same)
Examples: Checkpoint Template Code
Here are examples of a checkpoint template code:
WSTD identifies the command line to use during the working (W) phase of a checkpoint which is saving (S) a database to tape (T), for a database (D).
BRDT identifies the command line to use during the begin (B) phase of a roll forward operation that is restoring (R) from disk (D) for a table (T).
Substitution Parameters in the Checkpoint Template File
The checkpoint template file can optionally include substitution parameters that can be filled in at run time, to specify things like:
• Which database directory to back up
• Which tape device the user specified in the Checkpoint dialog
The parameters consist of a “%” and a single uppercase character, as follows:
%T
The type of operation: 0 if to tape, 1 if to disk.
%N
The total number of locations being written.
%M
For the begin or end operations, the incremental/current location number. For save or restore operations, this starts at 1 and is incremented after each save or restore command.
%D
The path to the database directory being saved or restored.
%C
The path to the checkpoint directory of disk files or the device name if to tape.
%F
The name of the checkpoint file created or read from.
%A
%C prepended to %F in a form to produce a fully specified file (that is, %A = %C/%F).
%X
The name of the table, pertinent to the work commands executed under table processing.
%B
Expanded during execution to represent the list of internal files that are associated with a table checkpoint. This parameter is pertinent to the work commands executed under table processing.
The “%” parameters in the commands are replaced by ckpdb and/or rollforwarddb when the command is executed.
Valid Code Combinations in the Checkpoint Template File
The valid code combinations in the checkpoint template file are shown here:
B [S,R,E,J,U] [T,D,E] [T,D,E,A]
P [S,R] [T,D] [D,T]
W [S,R,E,J,U,D,C] [T,D,E] [T,D,E,A]
I [,R,E] [T,D,E] [T,E]
F [,R,E] [T,D,E] [T,E]
E [S,E] [T,D] [D,T,E]
For every entry with a first character of B, there must be an accompanying entry beginning with E.
This section demonstrates how the codes are used in the checkpoint template file to perform checkpointing and roll forward operations in a variety of ways.
Checkpointing
The checkpointing operation (ckpdb command) executes the following sequence of codes in the cktmpl.def file:
Bsxy Beginning checkpoint
Wsxy Executed once for each location
Esxy Ending checkpoint
where:
x denotes D for disk, T for tape, or E for both.
y denotes D for database, T for table, or E for both.
Roll Forward
The roll forward operation (rollforwarddb command) processes the following codes in the cktmpl.file:
WCxA for each location
If table processing is specified, the following codes are executed:
BRxT once per location
IRxT once per location
WDxT for each table
WRxT for each table
FRxT once per location
EExE once (note that ERxT is executed if available)
If an entire database is being recovered (rather than specific tables), the following codes are executed:
BRxD once for each location
WDxD once for each location
WRxD once for each location
EExE once (note that ERxD is executed if available)
For all roll forward operations, the following codes are executed:
BUxA if dumps are to be applied
WUxA
EExE
BJxA if journals are to be applied
WJxA
EExE
Format of the Checkpoint Template File in Linux
The checkpoint template file, cktmpl.def, uses the Linux tar command. This file can be found in $II_SYSTEM/ingres/files.
Each line is a command preceded by a four-character code that instructs the checkpoint operation when to use the command.
By altering this file, you can change how checkpoints are performed. You can add or delete flags from the tar commands or you can supply your own shell scripts to perform the backup and restore steps.
For example, the command:
BSTD: echo beginning checkpoint to tape %C of
%N locations
indicates what is done initially, before the device is used (B), when the checkpoint operation is used to save (S) a database location to tape (T) for a database (D).
As another example, when executing a checkpoint on a database that spans multiple locations, the following command is executed once for each location:
PSTD: echo mount tape %N and press return;
read foo;
WSTD: cd %D; /bin/tar cbf 20 %C *
The command instructs the checkpoint operation to save each location on a tape and to use the tar command with the parameter cbf 20. The checkpoint utility automatically substitutes the appropriate value for “%N,” “%D,” and “%C.”
Archiver Exit Script (acpexit)
The Archiver Process Exit command script (acpexit) is executed by the archiver when it gets an error it cannot process that requires the archiver process to shut down.
This shell script resides in the files directory. You can use the default script behavior, which sends mail to the installation owner account with the reason for the archiver failure, or you can edit the script to customize certain aspects of archiver recovery.
Because the archiver writes sequentially to the end of journal files, a frequent problem occurs when the archiver stops as a result of running out of journal disk space. If left unresolved, running an installation without an archiver (and with journaled databases) eventually causes the log file to fill.
To address this concern, whenever the archiver detects an error condition that forces it to stop (including running out of journal disk space) it first executes the archiver exit script.
Customization of Archiver Exit Script
You can modify the archiver exit script to take action appropriate to your installation. For example, one possible course of action is to delete a reserved file on the journal disk to free up space and restart the archiver.
You can customize the archiver exit script in these respects:
• The default script sends mail to the installation owner account when archive processing halts and includes the reason for the failure. You can modify this script to notify the system administrator directly of a situation that needs resolving.
• You can tailor the script to handle certain resource and environmental problems automatically. For example, if archive processing has stopped because of insufficient disk space, the script can automatically reclaim disk space and resume archive processing.
• The default script is executed with one or two arguments, described in
Archiver Exit Script Parameters. You can choose whether to incorporate these arguments if you customize the script.
The default script includes examples of processing you can use for your installation. These examples are formatted as comments and can be included in the script by removing the comment prefixes.
Archiver Exit Script Parameters
The archiver exit script parameters are as follows: