PROUTIL DUMP qualifier

proutil db-name -C dump [owner-name.]table-name directory
[ tenant tenant-name | group group-name | partition partition-name
| composite initial ] [ -index num ]
[ [ -thread n ] [ -threadnum nthreads ] ]
[ -dumplist dumpfile ]
[ -Cipher 6 ]

Parameters

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.

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.

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.

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.

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.

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.

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.

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.

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).

For an Enterprise database enabled for Transparent Data Encryption, specify -Cipher 6 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 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

Table 97. 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.

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

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 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.

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 Dumping 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.

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 -Cipher 6 and entering a passphrase for the PBE cipher. You are prompted for the passphrase when loading the contents of the dump file.