PROBKUP utility

Backs up an OpenEdge RDBMS, including the database, before-image files, and transaction log (TL) extents. This utility can also enable after-imaging, AI File Management, and AI encryption during an online backup.

Syntax

probkup -help [ online ] db-name [ incremental ] device-name
          [ enableai [ -aiencryption { enable | disable } ] 
          [ enableaiarchiver -aiarcdir dirlist
               [ -aiarcinterval n ] [ -aiarcdircreate ] ] 
          [ bibackup { active | all } ] 
          [ -estimate | -vs n | -bf n | -verbose | -scan
             | -io i | [ -com  [-comlevel ] ] | -red i | -norecover ]
          [ -thread 0 | 1 ] [ -threadnum num-threads ] 
          [ -wbf num-write-buffers ]...

Parameters

-help

Displays syntax for utility and specified subcommands. If the syntax displayed ends with ellipses, type the command shown followed by -help to view subcommand syntax.

online

Indicates the backup is an online backup.

db-name

Specifies the database you want to back up.

incremental

Indicates the backup is an incremental backup.

device-name

Identifies a special device (for example, a tape drive) or a standard file. If device-name identifies a special device, PROBKUP assumes the device has removable media, such as a tape. For Windows, use \\.\tape0 for the device name if you are backing up to a tape drive.

enableai

Directs PROBKUP to enable after-imaging as part of the online backup process. The backup must be full and online to enable after-imaging. See After-imaging for more information on enabling after-imaging online.

-aiencryption { enable | disable }

If you are enabling after-imaging on an encryption-enabled database, -aiencryption explicitly enables or disables encryption of your AI files. If not specified, your AI files are encrypted or decrypted based on prior settings. You can determine the encryption status of your AI files with PROUTIL DESCRIBE; see PROUTIL DESCRIBE qualifier for more information. See Transparent Data Encryption for more information on encryption.

enableaiarchiver -aiarcdir dirlist

Directs PROBKUP to enable the AI File Management Utility as part of the online backup process. You must supply dirlist, a comma separated list of directories where archived after-image files are written by the AI File Management Utility. The directory names can not have any embedded spaces. In Windows, if you specify more than one directory, place dirlist in quotes. The directories must exist, unless you also specify -aiarcdircreate to direct the utility to create the directories. For more information, see AI File Management utility.

For details about listing multiple archiving directories, see After-image File Management Archive Directory List (-aiarcdir).

-aiarcdircreate

Directs the AI File Management utility to create the directories specified by -aiarcdir. For more information, see Enable an online database for automated AI file management during backup.

-aiarcinterval n

Include this parameter to specify timed mode operation of AI File Management. Omit this parameter for on-demand mode, and no mandatory extent switches other than when an extent is full. n sets the elapsed time in seconds between forced AI extent switches. The minimum time is 2 minutes, the maximum is 24 hours.

bibackup { active | all } 

For online backup ONLY, indicates whether to backup the active BI clusters or all the BI clusters. By default, only the active clusters are backed up.

If you do not specify bibackup all, online backup is not backward compatible with releases prior to OpenEdge Release 11.3.0.

-estimate

Indicates that the backup will give a media estimate only. Use the Scan parameter when using the Incremental or Compression parameters to get an accurate estimate.

Use -estimate for offline backups only. For online backups, PROBKUP performs a backup when the -estimate parameter is used.

-vs n

Indicates the volume size in database blocks that can be written to each removable volume. Before PROBKUP writes each volume, it displays a message that tells you to prepare the next volume. After writing each volume, a message tells you to remove the volume.

If you use the Volume Size parameter, the value must be greater than the value of the Blocking Factor parameter.

If you do not use -vs, PROBKUP assumes there is no limit and writes the backup until completion or until the volume is full. When the volume is full, PROBKUP prompts you for the next volume.

-bf n

Indicates the blocking factor for blocking data output to the backup device. The blocking factor specifies how many blocks of data are buffered before being transferred to the backup device. The primary use for this parameter is to improve the transfer speed to tape-backup devices by specifying that the data is transferred in amounts optimal for the particular backup device. The default for the blocking factor parameter is 34. The maximum value is 1024.

-verbose

Directs the PROBKUP utility to display information during the backup. If you specify the Verbose parameter, PROBKUP displays "Backed up n blocks in hh:mm:ss" every 10 seconds. If you do not specify the Verbose parameter, the message appears only once when the backup is complete.

-scan

Directs PROBKUP to perform an initial scan of the database and to display the number of blocks that will be backed up and the amount of media the backup requires. You cannot use the -scan parameter for online backups.

For full backups, if you specify -scan as well as -com, PROBKUP scans the database and computes the backup media requirements after the data is compressed.

-io i

Specifies an incremental overlap factor. The incremental overlap factor determines the redundancy among incremental backups. An incremental overlap factor of one (1) on every backup allows for the loss of one incremental backup in a backup series, as long as the immediate predecessor of that backup is not also lost. An overlap factor of two (2) allows for losing the two immediate predecessors. The default overlap factor is zero(0).

-com

Indicates that the data should be compressed prior to writing it on the backup media. The unused portion of index and record blocks is compressed to a 3-byte compression string. If you do not specify -com, there is no compression. If you do not specify a -comlevel option with -com, free blocks are compressed to the length of their header, 16 bytes. Specify a -comlevel option to control the compression speed and ratio.

-comlevel

Specifies a compression level. A lower compression level value yields higher compression speed, while a higher level yields higher data compression with the ZSTD compression algorithm.

• If you omit -com and -comlevel, no compression is performed.
• If you omit -com but specify -comlevel n, the specified -comlevel n is ignored. No compression is performed.
• If you specify -com without -comlevel, the default Zstandard (ZSTD) algorithm applies (compression level 3).

In this release, the default compression level has changed from Run-Length Encoding (RLE) to ZSTD.

-com	-comlevel	Compression algorithm applied
Not specified	Not specified	No compression
Not specified	Specified with level	No compression, -comlevel is ignored
Specified	Not specified	Applies the ZSTD algorithm using the default compression level 3. Changes the backup header version.
Specified	1	Applies the RLE compression algorithm. Free blocks are compressed to the length of their header, 16 bytes.
Specified	2	Applies the fastest, least compressed ratio of the ZSTD compression algorithm, and changes the backup header version.
Specified	3	Applies a ZSTD algorithm that balances speed versus compression ratio, and changes the backup header version.
Specified	4	Applies the slowest, most compressed ratio of the ZSTD compression algorithm, and changes the backup header version.

-red i

Sets the amount of redundancy to add to the backup for error correction. The value i is a positive integer that indicates the number of blocks for every error correction block. PROBKUP creates an error correction block for every i blocks and writes it to the backup media. You can use error correction blocks to recover corrupted backup blocks. The lower the redundancy factor, the more error correction blocks are created. If you specify a redundancy of one (1), you completely duplicate the backup, block for block. Because of the amount of time and media required to create the error correction blocks, use this parameter only if your backup media is unreliable. See Back Up a Database for more information about error correction blocks and data recovery.

-norecover

Do not perform crash recovery before backing up the database, but back up the BI files.

-thread 0 | 1

Disables multi-threading when -thread is omitted or set to 0, and enables multi-threading when -thread is set to 1. Multi-threading allows serial operations to run in parallel, improving performance. For examples, see Run a multi-threaded backup.

-threadnum num-thread

When multi-threading is enabled, this optional parameter controls the maximum number of threads created by the main process for a backup.

If -thread is specified and -threadnum is not specified, the default -threadnum is used.

The default -threadnum is the minimum between the number of CPUs on the system and the hard-coded value of six. These settings ensure that threading does not overwhelm the system. For example, if there are four CPUs on the system, the default -threadnum used is four. If there are eight CPUs on the system, the default -threadnum used is six. Although the default -threadnum is capped at six, a value that is equal to the number of CPUs in the system usually produces the best results.

-wbf

When multi-threading is enabled, this optional parameter specifies the number of write buffers used while writing data to the backup file. The size of each buffer is calculated as follows:

(Database-block-size * blocking-factor) + 48 bytes of header information

where blocking-factor is the value of the -bf parameter.

The value of -wbf ranges from 1 to 100,000, with the default of 1024. In general, you should tune this parameter only if memory usage is a concern.

Calculate the minimum value of -wbf as follows:

min -wbf = 2 * (1 + ((36 * 4) / -bf) + (-threadnum / -bf)))

For example, if -threadnum is eight and -bf is 34:

min -wbf = 2 * (1 + ((36 * 4) / 34)) + (8 / 34)) = 2 * (1 + (5) + (1)) = 14

If -wbf is set on the command line and is below the minimum value, or if the default -wbf is below the minimum value when -wbf is not set, then the write buffer factor is internally adjusted and the following message appears in the database log:

BACKUP 1: (-----) Adjusting write buffer factor (-wbf) to 14.

Notes

• When restoring a backup, the target database must contain the same physical structure as the backup version. For example, it must have the same number of storage areas, records, blocks, and blocksize.
• The minimum backup volume size is 34K.
• You cannot perform an online backup on:
  • A system running in single-user mode
  • A database that was started with the No Shared Memory (-noshm) parameter
  • A database that was started with the No Crash Protection (-i) parameter
• If after-imaging is enabled prior to this online backup, PROBKUP automatically switches to a new after-image (AI) file before starting the backup process, establishing a reference point from which to start your roll-forward recovery. Before you perform an online backup, verify that the next AI file is empty. If the next AI file is not empty, PROBKUP aborts the backup. See After-imaging for more information about AI files.
• If you run the PROBKUP utility at the same time another process is accessing the same backup device, you might receive a sharing violation error.
• If you use the Compression parameter (-com), you reduce the size of your backup by between 10 and 40 percent, depending on your database.
• Incremental backups vary in size according to the amount of changes made between incremental backups. Incremental backups that specify an Overlap (-io) value, also vary in size, depending on the amount of changes accumulated during the entire overlapping backup period. See Incremental backups for more information about incremental backups.
• If the BI file is not truncated before you perform a backup, the database engine performs database recovery.
• Enabling After-Image Management requires after-imaging to be enabled. Both can be enabled simultaneously or after-imaging can be previously enabled.
• Enabling After-Image Management directs the broker to start the AI Management daemon.
• See Back Up a Database for more information about performing backups.
• PROBKUP supports the use of internationalization startup parameters such as -cpinternal codepage and -cpstream codepage. See Database Startup Parameters for a description of each database-related internationalization startup parameter.
• PROBKUP enableai option automatically sets the AI block size to the same value as the BI block size. If the AI block size had previously been set to another value, this value will be ignored when PROBKUP enables AI. You must reset AI block size manually once BROPKUP has finished.
• PROBKUP allows you to use Private Read-Only Buffers (-Bp). An online backup using -Bp uses its own private buffer list instead of maintaining all the buffers that need to be read at the Least Recently Used (LRU) end of the buffer pool. Therefore, -Bp prevents the users from affecting the common buffer pool. Progress recommends using private buffers with an online PROBKUP to avoid the performance cost immediately after an online backup has completed. However, it should be noted that -Bp is not a parameter particular to online backup. Online backup is simply one application of it.

  $ PROBKUP online <dbname> <backup_path\backupvolume_name> -Bp n

  • The Private Buffer Pool (-Bp) is an isolated portion of the Public Buffer Pool (-B) and therefore does not consume additional shared memory than is currently allocated.
  • The total number of Private Buffers is limited to no more than 25% of the Primary Buffer Pool (-B) value.
  • If Private Buffers are also used by clients, consider increasing the database startup parameter -Bpmax (64 by default).
  • Incrementing the -Bp value is a tuning exercise, and results are likely to vary due to the inherent differences between environments and the dynamic nature of shared memory used by production databases. Given that the current number of database buffers for -B and -B2 are adequately scoped for the application context, an online backup is unlikely to require many more private buffers than the proposed figure.
• Threaded online backups require one database user connection for the main thread and one user connection for the writer thread. Additionally, half of the worker threads require a database user connection, rounding up when the number of worker threads is an odd number. The total number of user connections needed is two plus the 1/2 * -threadnum parameter value, rounded up.
• The following limitations affect all backups, whether the database is running or stopped:
  • Database write activity halts during backup of the before image and transaction logs.
  • Updates to database blocks in the backup wait until the block is backed up.