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.

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

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 Windows

The checkpoint template file uses the two batch files, ckcopyd.bat (for checkpointing to disk) and ckcopyt.bat (for checkpointing to tape).

The checkpoint template file, cktmpl.def, can be found in the folder %II_SYSTEM%\ingres\files.

Each line contains a command preceded by a four-character code that tells when to use the command.

By altering this file, or the two batch files that it calls, you can change how checkpoints are performed. You can add or delete flags to the underlying operating system commands, or you can supply your own batch files 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 checkpointing 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, one of the following commands is executed once for each location (WSTD for backup to tape, WSDD for backup to disk):

WSTD: ckcopyt %N %D BACKUP

WSDD: ckcopyd %D %A BACKUP

The commands instruct the checkpoint operation to call either the ckcopyt.bat or ckcopyd.bat batch command file to do the actual backup.

The checkpoint utility automatically substitutes the appropriate values for "%N," "%D," and "%A."

The ckcopyt.bat batch file calls the Windows backup backup command and passes it the name of the directory for the location, and other operating system flags.

Format of the Checkpoint Template File in UNIX

The checkpoint template file, cktmpl.def, uses the UNIX 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."

Format of the Checkpoint Template File in VMS

The checkpoint template file, cktmpl.def, can be found in $II_SYSTEM:[INGRES.FILES].

The checkpoint template file uses the four-letter key described above to begin each line. A line can specify an individual tape and disk handling command or the name of a user-written command file to provide more complex processing such as backing up all of a database's locations concurrently.

Defaults are provided so that sites using standard processing do not need to alter the checkpoint template file.

Here are some example lines from a cktmpl.def file:

WSTD: @ckp_to_tape "%N" "%D" "%C" "%F"
WSDD: @ckp_to_disk "%D" "%A"
WRTD: @rollfwd_from_tape "%N" "%D" "%C" "%F"
WRDD: @rollfwd_from_disk "%A" "%D"

Each of these example lines specifies the name of a command file and establishes requests for run-time information.

Alternate Checkpoint Template File in UNIX

The alternate checkpoint template file, cktmpl_cpio.def, uses the UNIX cpio command to backup and restore the database files. This file can be found in $II_SYSTEM/ingres/files.

To use this template file, enter the following command to override the default cktmpl.def template file:

ingsetenv II_CKTMPL_FILE $II_SYSTEM/ingres/files/cktmpl_cpio.def