Table of Contents Previous Next
Logo
FreezeScript : 37.7 Using dumpdb
Copyright © 2003-2008 ZeroC, Inc.

37.7 Using dumpdb

 
This section describes the invocation of dumpdb and provides advice on how to best use it.

37.7.1 Options

The tool supports the standard command-line options common to all Slice processors listed in Section 4.19. The options specific to dumpdb are described below:
• load SLICE
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.
• key TYPE
value TYPE
Specifies the Slice type of the database key and value. If these options are not specified, and the e option is not used, dumpdb obtains type information from the catalog.
• e
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.
If this option is not specified, and the key and value options are not used, dumpdb obtains type information from the catalog.
• o FILE
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.
• f FILE
Execute the descriptors in the file named FILE. The file’s <database> descriptor specifies the key and value types; therefore it is not necessary to supply type information.
• select EXPR
Only display those records for which the expression EXPR is true. The expression can refer to the symbols key and value.
• c, catalog
Display information about the databases in an environment, or about a particular database. This option presents the type information contained in the catalog (see Section 36.7).

37.7.2 Database Arguments

If dumpdb is invoked to examine a database, it requires two arguments:
• dbenv
The pathname of the database environment directory.
• db
The name of the database file. dumpdb opens this database as read-only, and traversal occurs within a transaction.
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.

37.7.3 Use Cases

The command line options described in Section 37.7.1 support several modes of operation:
• Dump an entire database.
• Dump selected records of a database.
• Emit a sample descriptor file.
• Execute a descriptor file.
• Examine the catalog.
These use cases are described in the following sections.

Dump an Entire Database

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
As a convenience, you may omit the key and value types, in which case dumpdb obtains them from the catalog (see Section 36.7):
$ dumpdb load Employee.ice db emp.db

Dump Selected Records

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

Creating a Sample Descriptor File

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.

Executing a Descriptor 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

Examine the Catalog

The c option displays the contents of the database environment’s catalog:
$ dumpdb c db
The output indicates whether each database in the environment is associated with an evictor or a map. For maps, the output includes the key and value types.
If you specify the name of a database, dumpdb only displays the type information for that database:
$ dumpdb c db emp.db
Table of Contents Previous Next
Logo