Performs a binary dump of a database table to a file.

Parameters

db-name

Specifies the name of the database from which you want to dump data. If the database is not within the current working directory, you need to define the complete path.

owner-name

Specifies the owner of the table containing the data you want to dump. You must specify an owner name unless the table name is unique within the database, or the table is owned by PUB. By default, ABL tables are owned by PUB.

table-name

Specifies the name of the table containing the data you want to dump.

directory

Specifies the name of the target directory where the data is to be dumped.

tenant tenant-name

Specifies that the DUMP operation is to be performed only on the table partitions of tenant-name. If tenant-name is not a valid tenant, DUMP exits with an error. Specifying tenant is allowed only on the databases enabled for multi-tenancy.

group group-name

Specifies that the DUMP operation is to be performed only on the table partitions of group-name. If group-name is not a valid group, DUMP exits with an error. Specifying group is allowed only on the databases enabled for multi-tenancy.

partition partition-name

Specifies that the DUMP operation is to be performed only on the table partition partition-name. If partition-name is not valid, DUMP exits with an error. Specifying partition is only allowed on databases enabled for table partitioning.

composite initial

Specifies that the DUMP operation is to be performed on the composite initial partition. Specifying composite initial is allowed only on the databases enabled for table partitioning.

stopaftererror value

Stops the utility after reaching the specified number of errors. The default setting, zero, means no stopping despite any number of errors. The maximum value is a 32-bit LONG value, 2147483647. When recovering data from a corrupted database, this option enables the binary dump to continue instead of stopping on encountering the first error. The stopaftererror parameter also returns detail about the corruption present. For a multi-threaded dump, the stopaftererror value aggregates errors from all threads.

For examples, see Dump data from corrupted records with PROUTIL.

-index num

Specifies the index to use for dumping the table contents. Note that word indexes are not allowed. If you choose not to use this option, the command uses the primary index to dump the table.

-thread n

For databases with an Enterprise license, this option indicates if an online dump is threaded. Specify zero for a single-threaded dump and one for a threaded dump.

-threadnum nthreads

For a threaded dump, this option specifies the maximum number of threads to be created. The default value is the number of system CPUs. The actual number of threads created may be less than nthreads. PROUTIL DUMP determines the number of threads to be created based on the complexity of the index followed by the DUMP.

-dumplist dumpfile

Create a file, dumpfile, that lists all the files created by this utility. This dumpfile can be used as an input parameter to binary load (PROUTIL LOAD).

-Cipher cipher-id

For an Enterprise database enabled for Transparent Data Encryption, this option specifies whether -Cipher 11 or -Cipher 12 encrypts the output of the PROUTIL DUMP with a password-based encryption cipher (PBE). You are prompted to enter the passphrase for the cipher. You must remember this passphrase, to enter it when loading the binary dump.

-RO

Runs the utility in read-only mode. Use read-only mode to:

• Connect to databases on read-only media.
• Diagnose and repair issues on a stopped database before starting it.
• Make any number of connections at once (up to the maximum number) simultaneously, to reduce bottlenecks and expedite disaster recovery on large databases.

Note: Use -RO with caution because it is designed to work only with a read-only connection. Unexpected errors may result if you specify -RO when using a single-user or multi-user connection.

PROUTIL DUMP writes data from a table to one or more files. When the procedure finishes, it reports the number of records written to the dump file. For a threaded dump, the number of records written by each thread is also reported.

PROUTIL DUMP selects some or all of the records in the specified table to dump, based on the following parameters:

• When dumping the contents of a multi-tenant database, if no tenant or group is specified, then the entire table is dumped.
• When dumping the contents of a partitioned table, if no partition is specified, then the entire table is dumped.

PROUTIL DUMP output

PROUTIL DUMP data from a table to a file or multiple files. You can easily save the names of the files created during the dump process by specifying a list file with the -dumplist qualifier. These filenames follow a number of conventions depending on what is being dumped:

• The name of the dump files depends on the owner of the table. By default, ABL tables are owned by PUB. When tables owned by PUB are dumped to a file by an offline or single-threaded online dump, the filename is the table name with .bd appended. For example, tablename.bd.

  However, when tables owned by anyone other than PUB are dumped to a file, the filename is the owner name and table name. For example, ownername_tablename.bd

• If you dump a table larger than 2GB on systems that have a 2GB-file-size limitation, PROUTIL DUMP creates multiple files. For example, when you dump data from a table with the name customer that is 6.4GB, PROUTIL DUMP creates four binary dump files: customer.bd, customer.bd2, and customer.bd3, each of which is approximately 2GB, and customer.bd4, which is approximately 0.4GB. The PROUTIL DUMP procedure adds header blocks to the binary dump files, so their total size is slightly larger than the table itself.

  On systems without file size limitation, a single-threaded PROUTIL DUMP creates only one binary dump file regardless of the size of the table.

• For all threaded dumps, PROUTIL DUMP creates multiple files, one for each thread. The first thread creates the file tablename.bd; the second thread creates the file tablename.bd2; each additional thread creates a file with an incremental number, tablename.bdn.

• When dumping the contents of a multi-tenant or table-partitioned database, and a tenant, group, or partition is specified, the naming convention of the dump file is modified as shown:

  table-name_ID{T|G|P|C}_TPGCName.bdn

  The elements of the file name are described in the following table.

  Table 1. Binary dump file name description

  File name element	Description
  table-name	The name of the table being dumped. If the table is not owned by PUB, then the owner is prepended to the table name.
  ID	The ID of the tenant, group (without negative sign), or partition.
  {T|G|P|C}	Identifier: T indicates the ID is a tenant ID. G indicates the ID is a group ID. P indicates the ID is a table partition ID. C indicates the ID is the composite partition ID.
  TPGCName	The name of the tenant, group, table partition, or composite initial partition that corresponds to ID.
  n	The number of the binary dump files when more than one file is created during the dump of the table. The value of n is determined by either the size of the file or the number of threads created.

• For threaded dumps of a partitioned table, if you specify a local index with -index, each partition is dumped sequentially. The number of threads created for each partition (and therefore, the number of output files) depends on the depth of the index tree for the partition. If the index has only one level for a given partition, the dump of that partition is not threaded. The number of threads created for each partition displays as the dump progresses.

  If a global index is specified to dump a partitioned table, then the dump is not broken down by partition.

  For example, if you dump the list-range partitioned table, history, by a local index, the dump files created are named by partition: history_1P_hist_lr_1.bd, history_1P_hist_lr_1.bd2, and so on. If the same table is dumped by a global index, the dump files created are named by the table: , history.bd2, and so on.

Notes

• See Dumping and Loading for more information about the DUMP qualifier.
• The PROUTIL DUMP and LOAD utilities use cyclic redundancy check (CRC) values to establish the criteria for loading.

  The OpenEdge database provides a flexible storage architecture and the ability to relocate objects, such as tables and indexes, while the database remains online. As a result, when you perform a binary load operation, the table numbers in a binary dump file might not match those in the target database. Therefore, when performing a binary load operation, the criteria for loading tables is based solely on cyclic redundancy check (CRC) values, and not table numbers.

  For example, when you dump a table, the PROUTIL utility calculates a CRC value for the table and stores it in the header of the binary dump file. When you load the table, PROUTIL matches the CRC value stored in the header with the CRC value of the target table. If the values do not match, the load is rejected.

  You can load a binary dump file created with a previous version of the PROUTIL DUMP utility, because the current version of PROUTIL LOAD uses the CRC value established when the file was originally dumped. Consequently, the database maintains backwards compatibility.

• If the file specified by the -dumpfile option exists, PROUTIL DUMP overwrites the existing file.
• When you select a global index to dump a specific table partition, DUMP must perform a table scan, and its performance is slower than when a local index is selected.
• You cannot specify the composite initial partition with the partition qualifier, use composite initial.
• PROUTIL DUMP supports dumping binary large objects (BLOBS).
• Dumped data can only be loaded to a database with the same code page as the source database. Use the ASCII dump and load utilities to perform a code page conversion with your dump and load. For more information on the ASCII utilities, see Dump user table contents with a Data tool.
• You cannot use DUMP to dump protected audit data. For more information on auditing and utility security and restrictions, see Auditing impact on database utilities.
• Record changes should be avoided while running any type of online binary dump. Running applications that change record values can alter the final set of records recorded in the binary dump file. This can occur when a changed field value interferes with the scanning order that the binary dump process is using. If a record’s field value changes in this way while the binary dump process is running, the record may either be skipped or dumped more than once based on the current scan position at the time the field was changed or the qualified range criteria of the binary dump process.
• When dumping the contents of a table encrypted with Transparent Data Encryption, the output of the binary dump is not encrypted by default. Encrypt the dump file (container security) by specifying either -Cipher 11 or -Cipher 12 and entering a passphrase for the PBE cipher. You are prompted for the passphrase when loading the contents of the dump file.
• You can use this utility with a stopped database that has a read-only connection. See Read-only connections.