Verifies the integrity of a database backup or restores a full or incremental backup of a database.

Syntax

prorest -help dbname device-name { -vp | -vf | -list | -describe }
[ -dbrestrict restrict-type ][ -newinstance ][ -verbose ][ -noverify ] 
[ -thread 0 | 1 ] [ -threadnum num-threads ] [ -rbf num-read-buffers ]  
[ -wbf num-write-buffers ]

Parameters

-help
Displays syntax for utility and specified sub-commands. If the syntax displayed ends with ellipses, type the command shown followed by -help to view subcommand syntax.
db-name
Specifies the database where you want to restore the backups.
device-name
Identifies the directory pathname of the input device (for example, a tape drive) or a standard file from which you are restoring the data. If device-name identifies a block or character special device, PROREST assumes the device has removable media, such as a tape or a floppy diskette.
-vp
Specifies that the restore utility reads the backup volumes and computes and compares the backup block cyclic redundancy checks (CRCs) with those in the block headers. To recover any data from a bad block, you must have specified a redundancy factor when you performed the database backup. See Error-correction blocks for more information about error correction blocks and data recovery.
-vf
Specifies that the restore utility only compares the backup to the database block for block.
-list
Provides a description of all application data storage areas contained within a database backup. Use the information to create a new structure description (.st) file and database so you can restore the backup.
-describe
Provides a description of a database backup file. You can use this information to choose the best backup to restore your backup from. This qualifier is backwards compatible with previous versions of OpenEdge and cross-platform compatible. For more information about the -describe, see Obtain backup file descriptions using PROREST -describe utility.
-dbrestrict restrict-type

Protects the restored database from updates by other users by putting the database in a restricted access mode where restrict-type is one of the following values:

  • datamove—Indicates that the next allowable activity on this database is moving data with the datamove utility
  • partitioncopy—Indicates that the next allowable activity on this database is copying data with the partitionmanage copy utility

Adding -dbrestrict enables the same restrictions as PROUTIL DBRESTRICT. See PROUTIL DBRESTRICT qualifier for details of the restrictions.

-newinstance
Specifies that a new GUID be created for the target database.
-verbose

Displays additional information as the restore is performed, such as:

  • If the target of the restore doesn't exist, -verbose lists the target area size information.
  • For restore full verify (-vf) and restore partial verify (-vp), -verbose displays periodic updates that include the number of blocks verified, the elapsed time, and an estimate of the time remaining given the current rate of progress.
-noverify
Allows faster restore completion by skipping the cyclic redundancy checks (CRCs) of the backup block. The -noverify option is useful for recreating a database under time critical conditions, but is disabled by default.
Note: The CRC ensures that the backup file has no physical corruption. Running PROREST -vp (partial verification) routinely after each backup is the best practice. You may also run PROREST -vp in parallel with -noverify or after you restore the database.
-thread 0 | 1
Omitting -thread or setting -thread 0 disables multi-threading, and -thread 1 enables multi-threading. Multi-threading allows serial operations to run in parallel, improving performance. For examples, see Run a multi-threaded restore.
-threadnum num-thread
When multi-threading is enabled, this optional parameter controls the maximum number of threads created by the main process for a restore. The restore utility sets the maximum number of threads as follows:
  • If -threadnum is greater than zero and less than twice the number of CPUs on the running machine, then the specified -threadnum is the maximum number of threads.
  • If -threadnum is greater than twice the number of CPUs, PROREST resets -threadnum to twice the number of CPUs.
  • If -threadnum is omitted, then the number of CPUs is the maximum number of threads.
  • If -threadnum is zero, then multi-threaded restore is disabled.
These settings ensure that threading does not overwhelm the system.
-rbf

When multi-threading is enabled, this optional value specifies the number of read buffers when reading data from backup files. The size of each buffer is db blocksize * -bf value, where -bf is the value used to generate the backup file. For example, if database block size is 4KB, and the -bf value is 34 (which is the default value) when backing up the database, then the read buffer size is 144KB. With -rbf of 1024, the total memory allocated to read buffers is 1024 * 144KB = 144MB.

The value of -rbf ranges from 100 to 100,000, with default of 1024. On systems with limited resources, you can lower this value to reduce the memory usage.

-wbf

When multi-threading is enabled, this optional parameter specifies the number of write buffers when writing data to the target database. The size of each buffer is 64KB. The value of -wbf ranges from 1 to 100,000, with default of 1024.

The -wbf value must be greater than or equal to the value of the -threadnum parameter. If -threadnum is not specified, adjust -wbf to the number of CPUs. On systems with limited resources, you can lower this value to reduce the memory usage.

Notes

  • Restore a backup with the same OpenEdge release that you used to perform the backup. In most cases, you can restore a backup with any minor release within the same major release, with the following exceptions:
    • If you enabled a feature, you cannot restore your database to a release that does not support that feature, without first disabling the feature in your database. For example, if your database has Change Data Capture enabled, you cannot restore a backup of that database to an OpenEdge release that does not support Change Data Capture. Be aware that new VST tables are enabled by default starting in Release 11.5, and are a feature under this restriction. Use PROUTIL DESCRIBE to list the features enabled for your database.
    • For online backup ONLY: if you do not specify bibackup all, online backup is not backward compatible with releases prior to OpenEdge Release 11.3.0. The bibackup qualifier indicates whether to backup the active BI clusters or all the BI clusters. By default, only the active clusters are backed up.
  • 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 per block, and block size.
  • In OpenEdge Release 12.6 and later, performing PROREST on an existing database results in a target database with large file support enabled. See Database creation and large file support for more information.
    Note: PROREST does not ensure that the target database is sized to hold all the restored data. In the event that the target database is too small, the behavior of PROREST is unchanged; it exits with an error.
  • The -keeptargetlfe parameter is no longer supported. Running PROREST with -keeptargetlfe will no longer have any effect on the resulting database as it did in releases prior to OpenEdge Release 12.0.
  • PROREST creates storage areas that match the information provided by the -list qualifier. However, if you do not create and apply a structure definition (.st) file to your target database, PROREST creates one variable-length extent per area. To have multiple extents, you must create and apply a structure definition file to your target database before performing the restore.

    The following figure shows an example of the output generated by the -list qualifier.

    Table 1. Sample PROREST -list output
    OpenEdge Release 12
              Area Name: Schema Area
              Size: 11264, Records/Block: 32, Area Number: 6, Cluster Size: 1
              Area Name: Info Area
              Size: 1024, Records/Block: 32, Area Number: 7, Cluster Size: 1
              Area Name: Customer/Order Area
              Size: 6656, Records/Block: 32, Area Number: 8, Cluster Size: 8
              Area Name: Primary Index Area
              Size: 112, Records/Block: 1, Area Number: 9, Cluster Size: 8
              Area Name: Customer Index Area
              Size: 256, Records/Block: 1, Area Number: 10, Cluster Size: 64
              Area Name: Order Index Area
              Size: 8192, Records/Block: 32, Area Number: 11, Cluster Size: 64
              Area Name: Encryption Policy Area
              Size: 20448, Records/Block: 32, Area Number: 12, Cluster Size: 64
              Area Name: Audit Area
              Size: 4608, Records/Block: 32, Area Number: 20, Cluster Size: 8
              Area Name: Audit Index
              Size: 8704, Records/Block: 32, Area Number: 22, Cluster Size: 8

    Use the output of PROREST -list to calculate the size of each restored area as follows:

    area-size = (Size / records-per-block) * database-block-size

    For example, the size of the restored schema area is:

    area-size = (Size / records-per-block) * database-block-size
                    1,441,792 = (11264 / 32) * 4096

    If you do not know your database block size, the output of PROREST -vp or -vf provides the information.

  • PROREST restores transaction log (TL) extents.
  • If your database is enabled for transparent data encryption, you must restore your keystore file (dbname.ks). You must back up and restore your keystore independent of your database using operating system utilities. The keystore is not backed up by PROBKUP or restored by PROREST.
  • Before you restore a database, verify that your backup does not contain any corrupted blocks. You can use the PROREST utility to verify the integrity of a full or incremental backup of a database by using the Partial Verify or Full Verify parameters.
  • The Partial Verify or Full Verify parameters do not restore or alter the database. You must use the PROREST utility separately to restore the database.
  • You can use the Partial Verify parameter with both online and offline backups.
  • Use the Full Verify parameter immediately after performing an offline backup to verify that the backup is correct.
  • PROREST 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.