40.7 Using dumpdb
This section describes the invocation of dumpdb and provides advice on how to best use it.
Loads the Slice definitions contained in the file SLICE. This option may be specified multiple times if several files must be loaded. However, it is the user’s responsibility to ensure that duplicate definitions do not occur (which is possible when two files are loaded that share a common include file). One strategy for avoiding duplicate definitions is to load a single Slice file that contains only
#include statements for each of the Slice files to be loaded. No duplication is possible in this case if the included files use include guards correctly.
Indicates that a Freeze evictor database is being examined. As a convenience, this option automatically sets the database key and value types to those appropriate for the Freeze evictor, and therefore the
‑‑key and
‑‑value options are not necessary. Specifically, the key type of a Freeze evictor database is
Ice::Identity, and the value type is
Freeze::ObjectRecord. The latter is defined in the Slice file
Freeze/EvictorStorage.ice, however this file does not need to be explicitly loaded.
Create a file named FILE containing sample descriptors for the loaded Slice definitions. If type information is not specified,
dumpdb obtains it from the catalog. If the
‑‑select option is used, its expression is included in the sample descriptors. Database traversal does not occur when the
‑o option is used.
If dumpdb is invoked to examine a database, it requires two arguments:
To display catalog information using the -c option, the database environment directory
dbenv is required. If the database file argument
db is omitted,
dumpdb displays information about every database in the catalog.
The simplest way to examine a database with dumpdb is to dump its entire contents. You must specify the database key and value types, load the necessary Slice definitions, and supply the names of the database environment directory and database file. For example, this command dumps a Freeze map database whose key type is
string and value type is
Employee:
$ dumpdb ‑‑key string ‑‑value ::Employee \
‑‑load Employee.ice db emp.db
$ dumpdb ‑‑load Employee.ice db emp.db
If only certain records are of interest to you, the ‑‑select option provides a convenient way to filter the output of
dumpdb. In the following example, we select employees from the accounting department:
$ dumpdb ‑‑load Employee.ice \
‑‑select "value.dept == 'Accounting'" db emp.db
In cases where the database records contain polymorphic class instances, you must be careful to specify an expression that can be successfully evaluated against all records. For example,
dumpdb fails immediately if the expression refers to a data member that does not exist in the class instance. The safest way to write an expression in this case is to check the type of the class instance before referring to any of its data members.
In the example below, we assume that a Freeze evictor database contains instances of various classes in a class hierarchy, and we are only interested in instances of
Manager whose employee count is greater than 10:
$ dumpdb ‑e ‑‑load Employee.ice \
‑‑select "value.servant.ice_id == '::Manager' and \
value.servant.group.length > 10" db emp.db
Alternatively, if Manager has derived classes, then the expression can be written in a different way so that instances of
Manager and any of its derived classes are considered:
$ dumpdb ‑e ‑‑load Employee.ice \
‑‑select "value.servant.ice_isA('::Manager') and \
value.servant.group.length > 10" db emp.db
If you require more sophisticated filtering or scripting capabilities, then you must use a descriptor file. The easiest way to get started with a descriptor file is to generate a template using
dumpdb:
$ dumpdb ‑‑key string ‑‑value ::Employee \
‑‑load Employee.ice ‑o dump.xml
The output file dump.xml is complete and can be executed immediately if desired, but typically the file is used as a starting point for further customization. Again, you may omit the key and value types by specifying the database instead:
$ dumpdb ‑‑load Employee.ice ‑o dump.xml db emp.db
If the ‑‑select option is specified, its expression is included in the generated
<record> descriptor as the value of the
test attribute in an
<if> descriptor.
dumpdb terminates immediately after generating the output file.
Use the ‑f option when you are ready to execute a descriptor file. For example, we can execute the descriptor we generated in the previous section using this command:
$ dumpdb ‑f dump.xml ‑‑load Employee.ice db emp.db
The ‑c option displays the contents of the database environment’s catalog:
If you specify the name of a database, dumpdb only displays the type information for that database:
