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

Parameters

db-name

Specifies the database where the dump will occur. 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's 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 will 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 only allowed on 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 only allowed on 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 only allowed on databases enabled for table partitioning.

-index num

Specifies the index to use to dump the table's 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, indicate if an online dump is threaded. Specify zero (0) for a single-threaded dump, one (1) for a threaded dump.

-threadnum nthreads

For a threaded dump, specify the maximum number of threads to create. 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 create based on the complexity of the index the DUMP follows.

-dumplist dumpfile

Create a file, dumpfile, that lists all the files created by this utility. The file, 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, specify either -Cipher 11 or -Cipher 12 to encrypt 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; you will be prompted to enter the passphrase when loading the binary dump.

PROUTIL DUMP writes data from a table to a dump file or 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 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 created files by specifying a list file with the -dumplist qualifier. The names of the files created during the dump process 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 resulting filename contains the owner name and table name. For example, ownername_tablename.bd

• On systems that have a 2GB-file-size limitation, PROUTIL DUMP creates multiple files when you dump a table larger than 2GB. 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. As a result, the total size of the binary dump files is slightly larger than the table itself.

  On systems without 2GB-file-size limitation, PROUTIL DUMP, running singly threaded, 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 tenant, group (without negative sign), or partition ID.
  {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 file when more than one file is created during the dump of the table. The value of n is determined either by 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 is output to the screen as the dump progresses.

  If a global index is specified to dump a partitioned table, then the dump is not broken out 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, etc. If the same table is dumped by a global index, the dump files created are named by the table: history.bd, history.bd2, etc.

Notes

• See 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 the table numbers in the target database. Therefore, when you perform 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. The values must match or 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.
• If you choose a global index to dump a specific table partition, DUMP must perform a table scan, and performance will be slower than if 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 .
• You cannot use DUMP to dump protected audit data. For more information on auditing and utility security and restrictions, see .
• 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.