PROUTIL DUMPSPECIFIED qualifier

Performs a binary dump of selected records.

Syntax

proutil db-name -C dumpspecified [owner-name.]table-name.field-name
          operator1 low-value [ AND operator2 high-value] 
             directory 
         [ tenant tenant-name| group group-name| 
                     partition partition-name | composite initial]
         [stopaftererror value] 
         [-preferidx index-name] 
         [ -Cipher  cipher-id] [-RO ]

Parameters

db-name
Specifies the name of the database containing the data you want to dump. You must completely define the 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.
field-name
Specifies the name of the index field or the name of a component field of a compound index, to be used for selecting the data you want to dump. If field-name is an index or the name of a component field of a compound index, it is used to select the data you want to dump, otherwise the primary index is used.
operator1
Specifies the first operator in the range: EQ (equals to), GT (greater than), LT (less than), GE (greater than or equal to), or LE (less than or equal to).
low-value
Specifies the first value against which the field-name value is to be compared.
AND
Specifies a bracketed range for the binary dump. The first value and operator, combined with the second value and operator, define a subset. You cannot use AND to dump two sets of non-contiguous result.
operator2
Specifies the second operator in the range: LT (less than), or LE (less than or equal to).
high-value
Specifies the first value against which the field-name value is to be compared.
directory
Specifies the name of the target directory where the data is to be dumped. You must specify a directory.
tenant tenant-name
Specifies that the DUMPSPECIFIED operation is to be performed only on the table partitions of tenant-name. If tenant-name is not a valid tenant, DUMPSPECIFIED exits with an error. Specifying tenant is allowed only on databases enabled for multi-tenancy.
group group-name
Specifies that the DUMPSPECIFIED operation is to be performed only on the table partitions of group-name. If group-name is not a valid group, DUMPSPECIFIED exits with an error. Specifying group is allowed only on databases enabled for multi-tenancy.
partition partition-name
Specifies that the DUMPSPECIFIED operation is to be performed only on the table partition partition-name. If partition-name is not valid, DUMPSPECIFIED exits with an error. Specifying partition is allowed only 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 databases enabled for table partitioning.
stopaftererror value
Stops the utility after 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.
-preferidx index-name
By default, DUMPSPECIFIED uses the primary index to sort rows. Specifying a different index with -preferidx orders the rows by the specified index.
-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 DUMPSPECIFIED with a password-based encryption cipher (PBE). You are prompted to enter the passphrase for the cipher. You must remember this passphras, 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.

Notes

  • If a field needs to be compared to a string containing other than alpha characters (including spaces or numbers), enclose the string in single quotes. For example: ‘John Smith', ‘11-14-2001', or ‘25 Main St'.
  • Dumping the data using a character comparison is case-sensitive.
  • If specifying a monetary value, do not include the money unit. For example, instead of $5.50, enter 5.5.
  • If specifying a negative number, prepend a backslash (\) escape character to the minus sign. For example: proutil testdb -C dumpspecified "PUB.Item.Item-NUM" LT "\-90".
  • Dates must be entered as mm-dd-yyyy.
  • The value entered for field-name must be the name of an index field.
  • You cannot use DUMPSPECIFIED 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 either -Cipher 11 or -Cipher 12 and entering a passphrase for the PBE cipher. You will be prompted to enter the passphrase when loading the contents of the dump file.
  • 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 corruption is present, PROUTIL DUMPSPECIFIED returns errors with corruption details, the table number, partition identifier, and record identifier. Use the stopaftererror num parameter to limit the number of errors processed. For an example, see Dump data from corrupted records with PROUTIL.
  • When dumping the contents of a multi-tenant database, if no tenant or group is specified, then all the rows meeting the specification are dumped.
  • When dumping the contents of a table-partitioned table, if no partition is specified, then the entire table is dumped.
  • You can use this utility with a stopped database through a read-only connection. See Read-only connections.

  • When dumping the contents of a multi-tenant or table-partitioned database, and a tenant, group, partition, or composite initial 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 Table 1.

  • Under the following rare circumstances, running PROUTIL -C DUMPSPECIFIED on a database with corrupted rows returns errors beyond the specified range:
    • When using the primary index of the table
    • When the column specified to dumpspecified is not a key component of any index on the table